{"id":26157030,"url":"https://github.com/testingbot/testingbotctl","last_synced_at":"2026-04-24T19:31:37.182Z","repository":{"id":269335921,"uuid":"906307585","full_name":"testingbot/testingbotctl","owner":"testingbot","description":"A command line interface for the TestingBot platform. Run Maestro, XCUITest and Espresso.","archived":false,"fork":false,"pushed_at":"2026-04-21T10:34:39.000Z","size":1445,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-21T12:32:17.309Z","etag":null,"topics":["espresso","maestro","selenium","xcuitest"],"latest_commit_sha":null,"homepage":"https://testingbot.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/testingbot.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-12-20T15:54:32.000Z","updated_at":"2026-04-21T10:34:43.000Z","dependencies_parsed_at":"2026-01-22T06:06:54.220Z","dependency_job_id":null,"html_url":"https://github.com/testingbot/testingbotctl","commit_stats":null,"previous_names":["testingbot/testingbotctl"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/testingbot/testingbotctl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testingbot%2Ftestingbotctl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testingbot%2Ftestingbotctl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testingbot%2Ftestingbotctl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testingbot%2Ftestingbotctl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/testingbot","download_url":"https://codeload.github.com/testingbot/testingbotctl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testingbot%2Ftestingbotctl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32238285,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T13:21:15.438Z","status":"ssl_error","status_checked_at":"2026-04-24T13:21:15.005Z","response_time":64,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["espresso","maestro","selenium","xcuitest"],"created_at":"2025-03-11T09:38:14.779Z","updated_at":"2026-04-24T19:31:37.176Z","avatar_url":"https://github.com/testingbot.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://testingbot.com\"\u003e\n    \u003cimg src=\"resources/logo.svg\" alt=\"Maestro Cloud Testing\" width=\"400\"\u003e\n  \u003c/a\u003e\n  \u003cbr\u003e\n  \u003cstrong\u003eRun mobile tests on real devices in the cloud\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/testingbot/testingbotctl/actions/workflows/test.yml\"\u003e\n    \u003cimg src=\"https://github.com/testingbot/testingbotctl/actions/workflows/test.yml/badge.svg\" alt=\"Run Tests\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@testingbot/cli\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/v/@testingbot/cli.svg\" alt=\"npm version\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@testingbot/cli\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/dm/@testingbot/cli.svg\" alt=\"npm downloads\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/testingbot/testingbotctl/blob/main/LICENSE\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/l/@testingbot/cli.svg\" alt=\"license\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://testingbot.com\"\u003eWebsite\u003c/a\u003e\n  ·\n  \u003ca href=\"https://testingbot.com/support/app-automate/maestro\"\u003eDocumentation\u003c/a\u003e\n  ·\n  \u003ca href=\"https://www.npmjs.com/package/@testingbot/cli\"\u003enpm\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"demo/demo.gif\" alt=\"TestingBot CLI Demo\" width=\"700\"\u003e\n\u003c/p\u003e\n\n---\n\nRun **Espresso**, **XCUITest** and **Maestro** tests on real devices in the cloud.\n\n- **Real Devices** — Test on thousands of real iOS and Android devices\n- **Emulators \u0026 Simulators** — Fast feedback with virtual devices\n- **Parallel Execution** — Split tests across multiple devices with sharding\n- **CI/CD Ready** — Integrates with GitHub Actions, Jenkins, and more\n- **Live Results** — Watch tests run in real-time\n- **Artifacts** — Download videos, screenshots, and logs\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#installation\"\u003e\u003cstrong\u003eGet Started →\u003c/strong\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Installation\n\n```sh\nnpm install -g @testingbot/cli\n```\n\n**Requirements:** NodeJS 20 or higher\n\n## Authentication\n\nThe CLI requires TestingBot API credentials. You can authenticate in several ways:\n\n### Browser Login (Recommended)\n\n```sh\ntestingbot login\n```\n\nThis opens your browser for authentication. After logging in, your credentials are saved to `~/.testingbot`.\n\n### Other Methods\n\n- **Command-line options**: `--api-key` and `--api-secret`\n- **Environment variables**: `TB_KEY` and `TB_SECRET`\n- **Config file**: Create `~/.testingbot` with content `key:secret`\n\n## Commands\n\n### Maestro\n\nRun Maestro UI tests on real devices and emulators/simulators.\n\n```sh\ntestingbot maestro \u003capp\u003e \u003cflows...\u003e [options]\n```\n\n**Arguments:**\n- `app` - Path to your app file (.apk, .ipa, .app, or .zip)\n- `flows` - One or more paths to flow files (.yaml/.yml), directories, .zip files, or glob patterns\n\n**Device Options:**\n\n| Option | Description |\n|--------|-------------|\n| `--device \u003cname\u003e` | Device name (e.g., \"Pixel 9\", \"iPhone 16\") |\n| `--platform \u003cname\u003e` | Platform: Android or iOS |\n| `--deviceVersion \u003cversion\u003e` | OS version (e.g., \"14\", \"17.2\") |\n| `--real-device` | Use a real device instead of emulator/simulator |\n| `--orientation \u003corientation\u003e` | Screen orientation: PORTRAIT or LANDSCAPE |\n| `--device-locale \u003clocale\u003e` | Device locale (e.g., \"en_US\", \"de_DE\") |\n| `--timezone \u003ctimezone\u003e` | Timezone (e.g., \"America/New_York\", \"Europe/London\") |\n\n**Test Configuration:**\n\n| Option | Description |\n|--------|-------------|\n| `--name \u003cname\u003e` | Test name for dashboard identification |\n| `--build \u003cbuild\u003e` | Build identifier for grouping test runs |\n| `--include-tags \u003ctags\u003e` | Only run flows with these tags (comma-separated) |\n| `--exclude-tags \u003ctags\u003e` | Exclude flows with these tags (comma-separated) |\n| `-e, --env \u003cKEY=VALUE\u003e` | Environment variable for flows (can be repeated) |\n| `--config \u003cpath\u003e` | Path to a custom Maestro config file (default: config.yaml in project root) |\n| `--maestro-version \u003cversion\u003e` | Maestro version to use (e.g., \"2.0.10\") |\n\n**Network \u0026 Location:**\n\n| Option | Description |\n|--------|-------------|\n| `--throttle-network \u003cspeed\u003e` | Network throttling: 4G, 3G, Edge, airplane, or disable |\n| `--geo-country-code \u003ccode\u003e` | Geographic IP location (ISO country code, e.g., \"US\", \"DE\") |\n\n**Tunnel:**\n\n| Option | Description |\n|--------|-------------|\n| `-t, --tunnel` | Start a TestingBot tunnel for this test run (cannot be combined with `--async`) |\n| `--tunnel-identifier \u003cid\u003e` | Identifier for the tunnel, allowing multiple tunnels in parallel |\n\n**Output Options:**\n\n| Option | Description |\n|--------|-------------|\n| `--async` | Start tests and exit without waiting for results |\n| `-q, --quiet` | Suppress progress output |\n| `--report \u003cformat\u003e` | Download report after completion: html or junit |\n| `--report-output-dir \u003cpath\u003e` | Directory to save reports (required with --report) |\n| `--download-artifacts [mode]` | Download test artifacts (logs, screenshots, video). Mode: `all` (default) or `failed` |\n| `--artifacts-output-dir \u003cpath\u003e` | Directory to save artifacts zip (defaults to current directory) |\n\n**Advanced Options:**\n\n| Option | Description |\n|--------|-------------|\n| `--shard-split \u003cnumber\u003e` | Split flows into N parallel sessions for faster execution |\n| `--ignore-checksum-check` | Skip checksum verification and always upload the app |\n\n**CI/CD Integration:**\n\n| Option | Description |\n|--------|-------------|\n| `--commit-sha \u003csha\u003e` | Git commit SHA associated with this test run |\n| `--pull-request-id \u003cid\u003e` | Pull request ID this test run originated from |\n| `--repo-name \u003cname\u003e` | Repository name (e.g., GitHub repo slug) |\n| `--repo-owner \u003cowner\u003e` | Repository owner (e.g., GitHub organization or username) |\n\n**Examples:**\n\n```sh\n# Basic usage\ntestingbot maestro app.apk ./flows\n\n# Multiple flow directories\ntestingbot maestro app.apk ./flows/smoke ./flows/regression ./flows/e2e\n\n# With device selection\ntestingbot maestro app.apk ./flows --device \"Pixel 8\" --deviceVersion \"14\"\n\n# Android app on real device with tags\ntestingbot maestro app.apk ./flows --device \"Samsung Galaxy S24\" --real-device --include-tags \"smoke,regression\"\n\n# With environment variables\ntestingbot maestro app.apk ./flows -e API_URL=https://staging.example.com -e API_KEY=secret\n\n# Download JUnit report\ntestingbot maestro app.apk ./flows --report junit --report-output-dir ./reports\n\n# Download all artifacts (logs, screenshots, video)\ntestingbot maestro app.apk ./flows --download-artifacts --build \"build-123\"\n\n# Download artifacts only for failed tests\ntestingbot maestro app.apk ./flows --download-artifacts failed --artifacts-output-dir ./artifacts\n\n# Use a custom config file\ntestingbot maestro app.apk ./flows --config .maestro/ci-config.yaml\n\n# Run in background (async)\ntestingbot maestro app.apk ./flows --async\n\n# Split flows across 3 shards, grouping all flows over 3 parallel sessions\ntestingbot maestro app.apk ./flows --shard-split 3\n\n# CI/CD integration with Git metadata\ntestingbot maestro app.apk ./flows \\\n  --commit-sha \"abc123def\" \\\n  --pull-request-id \"42\" \\\n  --repo-owner \"myorg\" \\\n  --repo-name \"myapp\"\n```\n\n---\n\n### Espresso\n\nRun Android Espresso tests on real devices and emulators.\n\n```sh\ntestingbot espresso [appFile] [testAppFile] [options]\n```\n\n**Arguments:**\n- `appFile` - Path to application APK file\n- `testAppFile` - Path to test APK file containing Espresso tests\n\n**Device Options:**\n\n| Option | Description |\n|--------|-------------|\n| `--app \u003cpath\u003e` | Path to application APK file |\n| `--test-app \u003cpath\u003e` | Path to test APK file |\n| `--device \u003cname\u003e` | Device name (e.g., \"Pixel 6\", \"Samsung.*\") |\n| `--platform-version \u003cversion\u003e` | Android OS version (e.g., \"12\", \"13\", \"14\") |\n| `--real-device` | Use a real device instead of an emulator |\n| `--tablet-only` | Only allocate tablet devices |\n| `--phone-only` | Only allocate phone devices |\n| `--locale \u003clocale\u003e` | Device locale (e.g., \"en_US\", \"de_DE\") |\n| `--timezone \u003ctimezone\u003e` | Timezone (e.g., \"America/New_York\", \"Europe/London\") |\n\n**Test Configuration:**\n\n| Option | Description |\n|--------|-------------|\n| `--name \u003cname\u003e` | Test name for dashboard identification |\n| `--build \u003cbuild\u003e` | Build identifier for grouping test runs |\n| `--test-runner \u003crunner\u003e` | Custom test instrumentation runner |\n| `--language \u003clang\u003e` | App language (ISO 639-1 code, e.g., \"en\", \"fr\", \"de\") |\n\n**Test Filtering:**\n\n| Option | Description |\n|--------|-------------|\n| `--class \u003cclasses\u003e` | Run tests in specific classes (comma-separated fully qualified names) |\n| `--not-class \u003cclasses\u003e` | Exclude tests in specific classes |\n| `--package \u003cpackages\u003e` | Run tests in specific packages (comma-separated) |\n| `--not-package \u003cpackages\u003e` | Exclude tests in specific packages |\n| `--annotation \u003cannotations\u003e` | Run tests with specific annotations (comma-separated) |\n| `--not-annotation \u003cannotations\u003e` | Exclude tests with specific annotations |\n| `--size \u003csizes\u003e` | Run tests by size: small, medium, large (comma-separated) |\n\n**Network \u0026 Location:**\n\n| Option | Description |\n|--------|-------------|\n| `--throttle-network \u003cspeed\u003e` | Network throttling: 4G, 3G, Edge, or airplane |\n| `--geo-location \u003ccode\u003e` | Geographic IP location (ISO country code, e.g., \"US\", \"DE\") |\n\n**Tunnel:**\n\n| Option | Description |\n|--------|-------------|\n| `-t, --tunnel` | Start a TestingBot tunnel for this test run (cannot be combined with `--async`) |\n| `--tunnel-identifier \u003cid\u003e` | Identifier for the tunnel, allowing multiple tunnels in parallel |\n\n**Output Options:**\n\n| Option | Description |\n|--------|-------------|\n| `--async` | Start tests and exit without waiting for results |\n| `-q, --quiet` | Suppress progress output |\n| `--report \u003cformat\u003e` | Download report after completion: html or junit |\n| `--report-output-dir \u003cpath\u003e` | Directory to save reports (required with --report) |\n\n**Examples:**\n\n```sh\n# Basic usage with positional arguments\ntestingbot espresso app.apk app-test.apk --device \"Pixel 8\"\n\n# Using named options\ntestingbot espresso --app app.apk --test-app app-test.apk --device \"Pixel 8\"\n\n# Real device with specific Android version\ntestingbot espresso app.apk app-test.apk \\\n  --device \"Samsung Galaxy S24\" \\\n  --platform-version \"14\" \\\n  --real-device\n\n# Run specific test classes\ntestingbot espresso app.apk app-test.apk \\\n  --device \"Pixel 8\" \\\n  --class \"com.example.LoginTest,com.example.HomeTest\"\n\n# Run tests with annotations\ntestingbot espresso app.apk app-test.apk \\\n  --device \"Pixel 8\" \\\n  --annotation \"com.example.SmokeTest\" \\\n  --size \"small,medium\"\n\n# With network throttling and geolocation\ntestingbot espresso app.apk app-test.apk \\\n  --device \"Pixel 8\" \\\n  --throttle-network \"3G\" \\\n  --geo-location \"DE\" \\\n  --language \"de\"\n\n# Download JUnit report\ntestingbot espresso app.apk app-test.apk \\\n  --device \"Pixel 8\" \\\n  --report junit \\\n  --report-output-dir ./reports\n```\n\n---\n\n### XCUITest\n\nRun iOS XCUITest tests on real devices and simulators.\n\n```sh\ntestingbot xcuitest [appFile] [testAppFile] [options]\n```\n\n**Arguments:**\n- `appFile` - Path to application IPA file\n- `testAppFile` - Path to test ZIP file containing XCUITests\n\n**Device Options:**\n\n| Option | Description |\n|--------|-------------|\n| `--app \u003cpath\u003e` | Path to application IPA file |\n| `--test-app \u003cpath\u003e` | Path to test ZIP file |\n| `--device \u003cname\u003e` | Device name (e.g., \"iPhone 15\", \"iPad.*\") |\n| `--platform-version \u003cversion\u003e` | iOS version (e.g., \"17.0\", \"18.2\") |\n| `--real-device` | Use a real device instead of a simulator |\n| `--tablet-only` | Only allocate tablet devices |\n| `--phone-only` | Only allocate phone devices |\n| `--orientation \u003corientation\u003e` | Screen orientation: PORTRAIT or LANDSCAPE |\n| `--locale \u003clocale\u003e` | Device locale (e.g., \"DE\", \"US\") |\n| `--timezone \u003ctimezone\u003e` | Timezone (e.g., \"America/New_York\", \"Europe/London\") |\n\n**Test Configuration:**\n\n| Option | Description |\n|--------|-------------|\n| `--name \u003cname\u003e` | Test name for dashboard identification |\n| `--build \u003cbuild\u003e` | Build identifier for grouping test runs |\n| `--language \u003clang\u003e` | App language (ISO 639-1 code, e.g., \"en\", \"fr\", \"de\") |\n\n**Network \u0026 Location:**\n\n| Option | Description |\n|--------|-------------|\n| `--throttle-network \u003cspeed\u003e` | Network throttling: 4G, 3G, Edge, or airplane |\n| `--geo-location \u003ccode\u003e` | Geographic IP location (ISO country code, e.g., \"US\", \"DE\") |\n\n**Tunnel:**\n\n| Option | Description |\n|--------|-------------|\n| `-t, --tunnel` | Start a TestingBot tunnel for this test run (cannot be combined with `--async`) |\n| `--tunnel-identifier \u003cid\u003e` | Identifier for the tunnel, allowing multiple tunnels in parallel |\n\n**Output Options:**\n\n| Option | Description |\n|--------|-------------|\n| `--async` | Start tests and exit without waiting for results |\n| `-q, --quiet` | Suppress progress output |\n| `--report \u003cformat\u003e` | Download report after completion: html or junit |\n| `--report-output-dir \u003cpath\u003e` | Directory to save reports (required with --report) |\n\n**Examples:**\n\n```sh\n# Basic usage with positional arguments\ntestingbot xcuitest app.ipa app-test.zip --device \"iPhone 16\"\n\n# Using named options\ntestingbot xcuitest --app app.ipa --test-app app-test.zip --device \"iPhone 16\"\n\n# Real device with specific iOS version\ntestingbot xcuitest app.ipa app-test.zip \\\n  --device \"iPhone 15 Pro\" \\\n  --platform-version \"17.2\" \\\n  --real-device\n\n# iPad in landscape mode\ntestingbot xcuitest app.ipa app-test.zip \\\n  --device \"iPad Pro\" \\\n  --tablet-only \\\n  --orientation LANDSCAPE\n\n# With localization settings\ntestingbot xcuitest app.ipa app-test.zip \\\n  --device \"iPhone 16\" \\\n  --locale \"DE\" \\\n  --language \"de\" \\\n  --timezone \"Europe/Berlin\"\n\n# With network throttling and geolocation\ntestingbot xcuitest app.ipa app-test.zip \\\n  --device \"iPhone 16\" \\\n  --throttle-network \"3G\" \\\n  --geo-location \"DE\"\n\n# Download HTML report\ntestingbot xcuitest app.ipa app-test.zip \\\n  --device \"iPhone 16\" \\\n  --report html \\\n  --report-output-dir ./reports\n\n# Run in background\ntestingbot xcuitest app.ipa app-test.zip \\\n  --device \"iPhone 16\" \\\n  --async\n```\n\n---\n\n## Common Features\n\n### Real-time Progress\n\nBy default, the CLI shows real-time progress updates including:\n- Test status updates with actual device names (even when using wildcards)\n- Device allocation status\n- Live output from Maestro flows\n\nUse `--quiet` to suppress progress output.\n\n### Graceful Shutdown\n\nPress `Ctrl+C` to gracefully stop running tests. The CLI will:\n1. Stop all active test runs on TestingBot\n2. Clean up resources\n3. Exit with appropriate status code\n\nPress `Ctrl+C` twice to force exit immediately.\n\n### Report Downloads\n\nAll test frameworks support downloading reports after completion:\n\n```sh\n# JUnit XML format (for CI integration)\n--report junit --report-output-dir ./reports\n\n# HTML format (for human viewing)\n--report html --report-output-dir ./reports\n```\n\n### Artifact Downloads (Maestro only)\n\nDownload all test artifacts including logs, screenshots, and video recordings:\n\n```sh\ntestingbot maestro app.apk ./flows --download-artifacts --build \"my-build\"\n```\n\nArtifacts are saved as a zip file named after the `--build` value (or with a timestamp if not provided).\n\n## Exit Codes\n\n- `0` - All tests passed\n- `1` - One or more tests failed or an error occurred\n\n## Documentation\n\nFor more information, visit [TestingBot Documentation](https://testingbot.com/support).\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftestingbot%2Ftestingbotctl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftestingbot%2Ftestingbotctl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftestingbot%2Ftestingbotctl/lists"}