> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revyl.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Running Tests

> Run individual tests or complete workflows directly from your terminal. Get real-time feedback and integrate testing into your development workflow.

## Run a Single Test

Execute a test by name or ID:

```bash theme={null}
revyl test run login-flow
```

The CLI will:

1. Resolve the test name (from aliases or API)
2. Queue the test for execution
3. Stream progress to your terminal
4. Report the final result and, for a blocking human-terminal run, open its report

### Example Output

```
Running test: login-flow
Platform: android
Build: v1.2.3 (current)

Step 1/5: Tap the login button ✓
Step 2/5: Enter email address ✓
Step 3/5: Enter password ✓
Step 4/5: Tap Submit ✓
Step 5/5: Dashboard is visible ✓

✓ Test passed in 45s
Report: https://app.revyl.ai/report/abc123
```

### Run Options

| Flag | Description |
| - | - |
| `--build-version-id <id>` | Run against a specific build version |
| `--retries <n>` | Number of retry attempts (default: 1) |
| `--timeout <seconds>` | Maximum execution time (default: 3600) |
| `--no-wait` | Queue test and exit immediately |
| `--open` | Explicitly request report opening for a supported blocking human-terminal run |
| `--no-open` | Do not open the completed report |
| `--json` | Output results as JSON |
| `--verbose` | Show detailed execution logs |
| `--launch-var <key-or-id>` | Apply a stored organization launch variable (repeatable) |
| `--launch-env KEY=VALUE` | Apply an inline launch variable (repeatable) |
| `--launch-arg-set <name-or-id>` | Apply a stored ordered iOS argument set (repeatable) |
| `--launch-arg=<token>` | Append one exact, non-secret iOS argument token (repeatable) |
| `--no-inherited-launch-vars` | Ignore `REVYL_INHERITED_LAUNCH_ENV_VAR_IDS` entirely; explicit launch variables still apply |

Blocking human-terminal runs open completed reports by default. `--no-open`,
`--no-wait`, `--json`, `--github-actions`, CI, SSH, and other headless
executions suppress browser opening.

Stored argument sets are flattened in attachment and flag order, followed by
inline `--launch-arg` tokens in flag order. Explicit arguments precede iOS
`-KEY value` pairs generated from environment configurations. Inline tokens are
non-secret and can appear in shell history, process arguments, and reports.
Android-only test runs reject iOS arguments with an actionable error.

## Run a Workflow

Execute a workflow (multiple tests). The recommended way to build and run a workflow in one command:

```bash theme={null}
revyl run smoke-tests -w
```

This builds your app, uploads it, then runs all tests in the workflow. Use `--no-build` to run without rebuilding:

```bash theme={null}
revyl run smoke-tests -w --no-build
```

You can also use the explicit workflow command:

```bash theme={null}
revyl workflow run smoke-tests
```

### Example Output

```
Running workflow: smoke-tests
Tests: 5

[1/5] login-flow ✓ (32s)
[2/5] browse-products ✓ (28s)
[3/5] add-to-cart ✓ (41s)
[4/5] checkout ✗ (55s) - Validation failed
[5/5] logout ✓ (12s)

Results: 4 passed, 1 failed
Total time: 2m 48s
Report: https://app.revyl.ai/workflow-report/xyz789
```

### Workflow Options

Launch-configuration overrides apply to every compatible child test in the
workflow. Mixed workflows apply iOS argument sets to iOS children and skip them
for Android children.

| Flag | Description |
| - | - |
| `--github-actions` | Format output for GitHub Actions |
| `--launch-var <key-or-id>` | Apply a stored environment configuration to every child (repeatable) |
| `--launch-env KEY=VALUE` | Apply a non-secret inline environment value (repeatable) |
| `--launch-arg-set <name-or-id>` | Apply a stored iOS argument set to iOS children (repeatable) |
| `--launch-arg=<token>` | Append a non-secret inline iOS token to iOS children (repeatable) |
| `--no-inherited-launch-vars` | Ignore `REVYL_INHERITED_LAUNCH_ENV_VAR_IDS` entirely; explicit launch variables still apply |
| `--open` | Explicitly request report opening for a supported blocking human-terminal run |
| `--no-open` | Do not open the completed report |
| `--no-wait` | Queue the workflow and exit without opening a report |

## Full Pipeline: Build → Upload → Test

Use the `--build` flag with `revyl test run` to run the complete pipeline:

```bash theme={null}
revyl test run login-flow --build --platform android
```

This executes:

1. **Build** - Run your build command
2. **Upload** - Upload the artifact to Revyl
3. **Test** - Run the test against the new build

### Pipeline Options

| Flag | Description |
| - | - |
| `--build` | Build and upload before running |
| `--profile <name>` | Named local build profile (requires `--build`) |
| `--platform ios\|android` | Platform recipe inside the selected profile (requires `--build`) |
| `--retries <n>` | Retry attempts for the test |
| `--no-wait` | Don't wait for test completion |
| `--open` | Explicitly request report opening for a supported blocking human-terminal run |
| `--no-open` | Do not open the completed report |
| `--timeout <seconds>` | Test timeout |
| `--json` | JSON output |

### Example

```bash theme={null}
# Build Android, upload, and run test
revyl test run checkout-flow --build --platform android

# Run test without building (against existing build)
revyl test run checkout-flow
```

<Callout type="info" title="Early Validation">
  The CLI validates that the test exists before starting the build process. If you specify a test name that doesn't exist, you'll get an immediate error with a list of available tests.
</Callout>

## Full Pipeline: Build → Upload → Workflow

The recommended way to build and run a workflow in one command:

```bash theme={null}
revyl run smoke-tests -w
revyl run smoke-tests -w --platform android
```

This executes:

1. **Build** - Run your build command
2. **Upload** - Upload the artifact to Revyl
3. **Workflow** - Run all tests in the workflow against the new build

Use `--no-build` to run the workflow without rebuilding (e.g. `revyl run smoke-tests -w --no-build`).

### Workflow pipeline options (with `revyl run <name> -w`)

| Flag | Description |
| - | - |
| `--no-build` | Skip build step; run against last uploaded build |
| `--platform <name>` | Build platform to use |
| `--retries <n>` | Retry attempts for each test |
| `--no-wait` | Don't wait for workflow completion |
| `--open` | Explicitly request report opening for a supported blocking human-terminal run |
| `--no-open` | Do not open the completed report |
| `--timeout <seconds>` | Workflow timeout |
| `--json` | JSON output |

### Alternative: `revyl workflow run`

You can also use `revyl workflow run` with the `--build` flag:

```bash theme={null}
revyl workflow run smoke-tests --build --platform android
```

| Flag | Description |
| - | - |
| `--build` | Build and upload before running workflow |
| `--profile <name>` | Named local build profile (requires `--build`) |
| `--platform ios\|android` | Platform recipe inside the selected profile (requires `--build`) |

## Build and Upload Only

Upload a build without running tests:

```bash theme={null}
revyl build --profile release --platform android
```

This builds in the cloud. Test/workflow `--build` remains local. See
[Build Configuration](/remote-builds/configuration).

### Upload Options

| Flag | Description |
| - | - |
| `--profile <name>` | Named local build profile to use |
| `--platform ios\|android` | Platform recipe inside the selected profile |
| `--version <string>` | Version label (default: `<branch-slug>-<timestamp>`) |
| `--no-set-current` | Do not set the uploaded build as the current/default build |
| `--json` | JSON output |

### Example Output

```
Building Android platform...
Running: ./gradlew assembleRelease
✓ Build completed in 45s

Uploading app-release.apk...
✓ Uploaded 24.5 MB in 8s

Build Version: bv_abc123
Package ID: com.example.app
Version: feature-new-login-20260227-153000 (branch-aware default)
```

<Callout type="info" title="Build artifact requirements">
  Default debug builds from every framework satisfy Revyl's artifact rules. For release builds, `.ipa` archives, or narrowed `abiFilters`, see [Build Artifact Requirements](/builds/artifact-requirements).
</Callout>

## List Builds

View uploaded build versions:

```bash theme={null}
revyl build list
```

Options:

| Flag | Description |
| - | - |
| `--platform <ios\|android>` | Filter by platform |
| `--build-var <id>` | Filter by build variant |
| `--json` | JSON output |

## Exit Codes

The CLI uses standard exit codes for scripting:

| Code | Meaning |
| - | - |
| `0` | Test/workflow passed |
| `1` | Test/workflow failed or error |

### CI/CD Example

```bash theme={null}
#!/bin/bash
revyl workflow run smoke-tests

if [ $? -eq 0 ]; then
  echo "All tests passed!"
  ./deploy.sh
else
  echo "Tests failed, aborting deployment"
  exit 1
fi
```

## JSON Output

For programmatic use, get structured JSON output:

```bash theme={null}
revyl test run login-flow --json
```

```json theme={null}
{
  "success": true,
  "task_id": "task_abc123",
  "test_name": "login-flow",
  "platform": "android",
  "execution_time": 45,
  "total_steps": 5,
  "completed_steps": 5,
  "report_link": "https://app.revyl.ai/report/abc123"
}
```

## Open Results in Browser

Blocking human-terminal test and workflow runs open the completed report by
default. To state the intent explicitly:

```bash theme={null}
revyl test run login-flow --open
```

Suppress browser opening with `--no-open`. No-wait, JSON, GitHub Actions, CI,
SSH, and other headless runs never open a browser.

Or open a previous report:

```bash theme={null}
revyl test open login-flow
```

## Background Execution

Queue a test without waiting for results:

```bash theme={null}
revyl test run login-flow --no-wait
```

Output:

```
Test queued: login-flow
Task ID: task_abc123
Track progress: https://app.revyl.ai/task/abc123
```

## Common Workflows

### Quick Smoke Test

```bash theme={null}
# Build, upload, and run workflow (recommended)
revyl run smoke-tests -w

# Or run workflow without rebuilding
revyl run smoke-tests -w --no-build
```

### Test New Changes

```bash theme={null}
# Build, upload, and test (recommended)
revyl run login-flow --platform android
```

### CI/CD Pipeline

```bash theme={null}
# In your CI script
export REVYL_API_KEY=${{ secrets.REVYL_API_KEY }}

# Build and upload
revyl build --profile release --platform android --version $GITHUB_SHA

# Run workflow, fail pipeline if tests fail
revyl workflow run regression --retries 2
```

### Local Development Loop

```bash theme={null}
# Make code changes
# ...

# Quick test without rebuilding
revyl run login-flow --no-build

# Full rebuild and test
revyl run login-flow --platform android
```

## Troubleshooting

### Cancelling a Running Test

Use `revyl test cancel` or `revyl workflow cancel` to request cancellation of a running test or workflow:

```bash theme={null}
# Cancel a running test
revyl test cancel <task_id>

# Request cancellation of a workflow and its tests
revyl workflow cancel <task_id>
```

**Where to find the task ID:**

* CLI output when starting a test: `Task ID: abc123-def456...`
* Report URL: `https://app.revyl.ai/tests/report?taskId=abc123...`

<Callout type="info" title="Note">
  A successful command can acknowledge a durable cancellation request while execution is still stopping. Check the returned test status or the workflow's child statuses for terminal completion.
  Retrying a stop preserves the session's existing terminal outcome and can resume pending cleanup.
</Callout>

<Callout type="warning" title="Ctrl+C vs Cancel">
  Pressing Ctrl+C only stops the CLI from monitoring - the test continues running on the server. Use `revyl test cancel <task_id>` to actually stop the test.
</Callout>

### Test Times Out

* Increase timeout: `--timeout 900`
* Check device availability in Revyl dashboard
* Verify the test runs manually in the web UI

### Build Upload Fails

* Check your build command produces output at the expected path
* Verify file permissions on the artifact
* Try `--dry-run` to see what would be uploaded

### "Test not found" Error

* Run `revyl test list` to see available tests
* Check spelling and case sensitivity
* Ensure the test exists in your `config.yaml` aliases or on remote


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.