install
The install command group manages Doc Detective’s runtime assets. By default, npm i doc-detective pre-installs these assets at postinstall. Use this command to manually install or reinstall assets, install only specific components, or inspect what’s currently installed.
If you opted out of postinstall pre-installation with DOC_DETECTIVE_AUTOINSTALL=0, assets install lazily on first use. Use doc-detective install all --yes to pre-install them manually.
Synopsis
Subcommands
install all
Install the lazy-installed runtime assets: npm packages, browser binaries, and (on Windows) Git Bash.
This is the recommended way to prepare a fresh environment or container image for running tests without first-run delays. It excludes agent tools (install agents, which needs an interactive picker) and the mobile toolchains (install android, whose multi-GB downloads stay opt-in, and install ios, which is macOS-only). Install those groups separately.
install agents
Install agent tools for AI coding assistants. Detects supported agents on your machine, prompts you to choose which to configure, and invokes each agent’s native install mechanism.
To target a specific agent non-interactively:
Supported --agent ids: claude, copilot, gemini, codex, qwen, opencode.
The --agent and --scope options are specific to install agents. Using --yes non-interactively requires both.
The older doc-detective install-agents form still works as a hidden alias, so existing scripts and CI jobs don’t need to change.
install runtime
Install heavy npm packages into the cache directory. Doc Detective downloads these packages (webdriverio, appium, sharp, etc.) on first use if not pre-installed.
Without arguments, installs all heavy dependencies. Specify package names to install only specific packages:
install browsers
Install browsers and their drivers into the cache directory.
Without arguments, installs Chrome, Firefox, ChromeDriver, and Geckodriver. Specify names to install only specific browsers or drivers:
Available names: chrome, firefox, chromedriver, geckodriver.
Some assets have no installable build for the current platform and architecture. Chrome and ChromeDriver on linux/arm64 are one example, since Google’s Chrome for Testing doesn’t publish them natively. Doc Detective skips those rather than failing the whole command, and the report shows them as skipped. Run doc-detective install status to see what actually installed.
install bash
Install Git Bash on Windows hosts. runShell runs commands in bash by default on every platform (see Shell selection), and this command provisions the bash that backs it on Windows.
If Git for Windows is already installed, the command reports it and downloads nothing. Otherwise it downloads a portable MinGit (about 40 MB, checksum-verified) into <cacheDir>/tools/git-bash. On macOS and Linux the command is a no-op, because those platforms use the bash on your PATH.
Running this ahead of time is optional. The first test run that needs bash on a Git-less Windows host installs it lazily. This command only pre-warms the cache, which suits CI images. Doc Detective verifies the install by running bash --version and repairs a corrupted copy automatically. Use --force to reinstall manually.
install android
Install the Android SDK toolchain (platform-tools, emulator, a system image) and create Doc Detective’s default AVD. Tests that target the android platform can then run. That covers both native Android app tests (native app phase A3) and mobile web tests in the device’s Chrome (phase A5). The system images it installs are the google_apis kind, which include Chrome. An emulator created from an image without Chrome skips mobile web tests with a pointer back to this command.
This command augments an existing SDK when it finds one through ANDROID_HOME, ANDROID_SDK_ROOT, or adb on your PATH. It runs sdkmanager and avdmanager from that SDK to add only the missing pieces and create the default AVD. When no SDK exists, it bootstraps Google’s command-line tools into <cacheDir>/android-sdk first.
Because the system image is multi-GB, this command never downloads without --yes. Run it with --dry-run first to preview the plan:
Google’s SDK repository occasionally serves a corrupt or truncated package. install android self-heals these transient download failures. It retries the affected sdkmanager download a few times. If a system image lands incomplete, it re-downloads that image once before continuing, so a momentary flake no longer fails the whole install. A genuine failure, such as an unavailable image or a rejected license, still stops with a clear message. Suppose a freshly downloaded system image is still incomplete after that one repair. install android logs an error, records it in the report as [android] system-image — corrupt, and stops before creating the AVD rather than building on a bad image. This outcome doesn’t set a non-zero exit code. Scripts should therefore watch the report or logs for corrupt instead of the exit status. Re-run the command to fetch a clean copy. The integrity check covers only images from the current run, so install android never touches a system image you already had.
sdkmanager and avdmanager need a Java runtime (JRE 17+). install android uses the one your host already has. Otherwise Doc Detective downloads a portable Temurin JRE into its cache as part of the confirmed install. Java isn’t a prerequisite you set up yourself. install android is not part of install all, because the multi-GB downloads are opt-in. You install the Android toolchain deliberately, not as a side effect of preparing a general test environment.
Running this ahead of time is optional but recommended. A test run that targets android on a capable host lazily installs the toolchain the first time it needs it. A capable host is one that can run the emulator. The run prints a clear warning to the terminal and the output report. Running install android beforehand pre-warms the cache so that cost isn’t paid mid-run, which suits CI images and containers. To forbid the lazy install entirely, set DOC_DETECTIVE_NO_ANDROID_AUTOINSTALL=1. The context then SKIPs with a pointer back to this command, which suits an air-gapped host that must never auto-download. A host that can’t run the emulator, lacking hardware acceleration, always SKIPs without downloading anything.
install ios
Prepare a macOS host for tests that target the ios platform. The command verifies the simulator prerequisites, installs the XCUITest driver, and prebuilds WebDriverAgent. Your first iOS test session then doesn’t spend ~10 minutes compiling it.
The command runs these steps and reports each individually. None of them fail the command. A step that can’t run reports skipped with guidance:
- Prerequisite checks. Verifies that the Xcode command-line tools resolve (
xcode-select -p) and that the iOS Simulator control tool responds (xcrun simctl). It gives actionable guidance when either is missing. - Driver install. Installs
appium-xcuitest-driverinto the Doc Detective cache if it isn’t already present. That’s the same install a first test run performs lazily. - WebDriverAgent prebuild. When full Xcode 14+ is present, this compiles the WebDriverAgent that ships inside the driver once for the iOS Simulator. It stores the result in the cache, keyed by your Xcode and driver versions (
<cacheDir>/ios/wda/…). If a build for the current key already exists, the step is a fast check-and-skip. Test sessions then use these build products automatically and read-only, so concurrent runs can safely share one cache. A session that finds no matching products builds WebDriverAgent itself, exactly as before.
Preview the plan on any host (including Windows/Linux, where it reports that iOS is macOS-only) with --dry-run:
The simulator itself is provisioned automatically at test time. A run that targets ios on a capable macOS host resolves and boots a simulator through simctl. It uses the newest installed iPhone by default, or a device named in your device descriptor, creating it if needed. install ios is not part of install all, because iOS preparation is macOS-only. On a non-macOS host, or a macOS host without Xcode or simctl, an ios context SKIPs with a pointer back to this command rather than failing.
Running this ahead of time is optional but recommended for CI. Persist the cache directory across runs (see Cache directory) and run install ios --yes when preparing the environment. The first run pays the WebDriverAgent build once. Every later run skips it, as does every parallel job sharing the cache. A driver or Xcode update produces a new key. The next install ios builds it, and in the meantime sessions fall back to building in-session. If you manage WebDriverAgent build products yourself, setting DOC_DETECTIVE_IOS_WDA_DERIVED_DATA_PATH still overrides everything, unchanged.
install status
Report what’s currently installed in the cache directory versus what the current Doc Detective version expects.
Because status only reads the cache, the install-specific flags (--yes, --force, --dry-run) have no effect on it. Only --cache-dir, --verbose, and --silent change its behavior.
Shared options
Every install subcommand takes these options:
Install log
During install all and install runtime, Doc Detective writes the full npm output to <cacheDir>/runtime/install.log. The terminal shows only filtered progress. The log file captures everything, including deprecation warnings and dependency resolution details.
If installation fails, the error message includes the log path:
Check this log to diagnose network issues, authentication problems, or native build failures that the filtered terminal output hides.
Cache directory
By default, runtime assets install to <os.tmpdir()>/doc-detective/. This location may not persist across reboots on some systems.
To set a persistent cache location:
- Environment variable:
DOC_DETECTIVE_CACHE_DIR=/opt/doc-detective - Config file: Set
cacheDirin.doc-detective.json - CLI flag:
--cache-dir /opt/doc-detective
Priority: environment variable > config file > default temp directory.
Examples
Pre-warm a container image for offline test runs:
Install only Chrome for lightweight browser tests:
Check what’s installed before running tests:
Force-update all browsers to the latest channel versions:
Troubleshooting installation failures
If install all or install runtime fails:
-
Check the install log: Open
<cacheDir>/runtime/install.logto see the full npm output, including errors the filtered terminal output hides. -
Run with verbose output: Use
--verboseto see npm’s output in real time: -
Check network and authentication: The log often reveals proxy issues, registry authentication failures, or network timeouts.
-
Retry with force: If a partial install left the cache in a bad state: