appium-chromium-environment-setup

Goal

Prepares a reliable Appium Chromium Driver environment by validating Node.js/npm, ensuring Appium 3 compatibility, installing the Chromium driver, validating browser/runtime prerequisites, and running a smoke test that confirms driver availability and server readiness.

Decision Logic

• If the host OS is not macOS, Linux, or Windows: stop and ask the user to use a supported OS.
• If current Node.js does not satisfy engines.node for both appium and appium-chromium-driver: install/upgrade Node.js to a compatible active LTS version.
• If current npm does not satisfy appium-chromium-driver engines.npm: upgrade npm before continuing.
• If Appium CLI is not installed: install appium globally.
• Use global npm/Appium commands by default (npm install -g appium, appium ...).
• Use local Appium commands (npx appium ...) only when the user explicitly requests local execution.
• If Appium major version is < 3: upgrade Appium to 3.x before installing or validating chromium.
• If the chromium driver is not installed: install it via Appium CLI.
• If install returns “already installed”, ignore the error and continue (or run driver update).
• If appium driver doctor chromium is supported and reports required fixes: resolve each required item and re-run doctor.
• If doctor is not supported for chromium in the active Appium/driver version: use install/list/smoke checks as the completion gate.
• If no supported Chromium-based browser is available (chrome/chromium/msedge): pause and ask the user which browser to automate and install.
• If no supported Chromium-based browser is available and the user explicitly approves optional browser setup: install Chrome or Chromium with OS-native package tooling, then re-run browser availability checks.
• If running inside WSL and browser install is requested: prefer distro package-manager installation as root in WSL (for example via wsl -u root) rather than user-space .deb extraction, because runtime shared-library dependencies are otherwise easy to miss.
• If Chrome is present but fails to start with missing shared libraries (for example libnspr4.so): treat this as an incomplete Linux dependency install and fix with package-manager dependencies before continuing.
• If the user does not request a pinned chromedriver version and no chromedriver binary is present in the environment: run appium driver run chromium install-chromedriver before smoke validation.
• If the user explicitly targets Microsoft Edge: treat msedgedriver setup as a separate optional step, require a driver version matching the installed Edge build, and pass it through appium:executable because automatic chromedriver download does not cover Edge.

Instructions

1. Prepare Node.js + npm environment macOS/Linux:

   node -v
   npm -v
   

   Windows PowerShell:

   node -v
   npm -v
   

   If node is missing, run environment-setup-node first (including Windows PowerShell profile bootstrap), then open a new terminal or run . $PROFILE, and re-run the commands.

2. Install/upgrade Appium and Chromium driver

   npm install -g appium@latest
   appium driver install chromium || appium driver update chromium
   appium driver list --installed --json || appium driver list --installed
   

   Prefer --json output for machine-readable verification. Confirm a chromium key is present; only fallback to plain-text output when --json is unsupported. If the install command fails only because chromium is already installed, continue and do not stop preparation.

3. Validate Appium command health and compatibility macOS/Linux:

   appium -v
   appium driver list --installed --json || appium driver list --installed
   npm view appium engines --json
   npm view appium-chromium-driver engines peerDependencies --json
   

   Windows PowerShell:

   appium -v
   appium driver list --installed --json; if ($LASTEXITCODE -ne 0) { appium driver list --installed }
   npm view appium engines --json
   npm view appium-chromium-driver engines peerDependencies --json
   

   Verify Appium major version is 3 and that active Node/npm versions satisfy the reported ranges.

4. Validate browser availability (Chrome/Chromium/Edge) macOS/Linux:

   command -v google-chrome || true
   command -v chromium || true
   command -v chromium-browser || true
   command -v msedge || true
   

   Windows PowerShell:

   Get-Command chrome.exe -ErrorAction SilentlyContinue
   Get-Command msedge.exe -ErrorAction SilentlyContinue
   

   Confirm at least one Chromium-based browser is available and note the target browser in the result summary.

   Optional browser setup (run only when the user explicitly requests it):

   • macOS (Homebrew):

     brew install --cask google-chrome
     # or
     brew install --cask chromium
     # or
     brew install --cask microsoft-edge
     

   • Linux (Debian/Ubuntu examples):

     sudo apt-get update
     sudo apt-get install -y chromium-browser || sudo apt-get install -y chromium
     # Microsoft Edge example
     curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > microsoft.gpg
     sudo install -o root -g root -m 644 microsoft.gpg /usr/share/keyrings/microsoft.gpg
     echo "deb [arch=amd64 signed-by=/usr/share/keyrings/microsoft.gpg] https://packages.microsoft.com/repos/edge stable main" | sudo tee /etc/apt/sources.list.d/microsoft-edge.list
     sudo apt-get update
     sudo apt-get install -y microsoft-edge-stable
     

   • WSL from Windows host (Debian/Ubuntu examples, no interactive sudo prompt):

     wsl -u root -e bash -lc "apt-get update"
     wsl -u root -e bash -lc "apt-get install -y libnspr4 libnss3 libxss1 libasound2t64 libatk-bridge2.0-0 libatk1.0-0 libcups2t64 libdrm2 libgbm1 libgtk-3-0 xdg-utils"
     wsl -u root -e bash -lc "apt-get install -y google-chrome-stable || apt-get install -y chromium-browser || apt-get install -y chromium"
     

   • Windows PowerShell (winget):

     winget install --id Google.Chrome --exact --accept-source-agreements --accept-package-agreements
     # or
     winget install --id Hibbiki.Chromium --exact --accept-source-agreements --accept-package-agreements
     # or
     winget install --id Microsoft.Edge --exact --accept-source-agreements --accept-package-agreements
     

     After installation, re-run the browser availability checks in this step.

5. Install chromedriver when missing (default) or pin it (on request) If the user does not request a specific chromedriver version, first check whether a chromedriver binary is available: macOS/Linux:

   command -v chromedriver || true
   

   Windows PowerShell:

   Get-Command chromedriver.exe -ErrorAction SilentlyContinue
   

   If no chromedriver binary is found, run:

   appium driver run chromium install-chromedriver
   

   Use version/directory pinning only when the user explicitly requests manual pinning or mirrored download flows. macOS/Linux examples:

   CHROMEDRIVER_VERSION=131.0.6778.3 appium driver run chromium install-chromedriver
   CHROMEDRIVER_EXECUTABLE_DIR=/path/to/dir appium driver run chromium install-chromedriver
   

   Windows PowerShell examples:

   $env:CHROMEDRIVER_VERSION='131.0.6778.3'; appium driver run chromium install-chromedriver; Remove-Item Env:\CHROMEDRIVER_VERSION
   $env:CHROMEDRIVER_EXECUTABLE_DIR='C:\path\to\folder'; appium driver run chromium install-chromedriver; Remove-Item Env:\CHROMEDRIVER_EXECUTABLE_DIR
   

   Optional Edge WebDriver setup (run only when the user explicitly requests Microsoft Edge automation):

   • Appium Chromium Driver does not autodownload msedgedriver.
   • Download the Microsoft Edge WebDriver version matching the installed Edge build from the official Microsoft Edge WebDriver page: https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/
   • Verify the installed Edge version first: macOS:

     defaults read "/Applications/Microsoft Edge.app/Contents/Info" CFBundleShortVersionString
     

     Linux:

     microsoft-edge --version
     

     Windows PowerShell:

     (Get-Item "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe").VersionInfo.ProductVersion
     

   • After downloading and extracting msedgedriver, place it in a stable path and confirm it works: macOS/Linux:

     chmod +x /path/to/msedgedriver
     /path/to/msedgedriver --version
     

     Windows PowerShell:

     & "C:\path\to\msedgedriver.exe" --version
     

   • For Edge sessions, pass the absolute driver path through capabilities:

     {
      "platformName": "macOS",
      "browserName": "MicrosoftEdge",
      "appium:automationName": "Chromium",
      "appium:executable": "/absolute/path/to/msedgedriver"
     }
     

6. Run Appium doctor for Chromium when supported

   appium driver doctor chromium
   

   Use 0 required fixes needed as the pass/fail gate when doctor is supported. Optional warnings are non-blocking. If required fixes remain, apply targeted fixes and re-run. If command output indicates the driver does not expose doctor checks, mark doctor as not-supported and continue with install/list/smoke checks.

7. Start Appium server smoke test

   appium server
   

   Windows PowerShell recommended form (for deterministic log checks):

   appium server --log "$env:TEMP\appium-chromium-smoke.log" --log-level info
   

   Keep this server process running in Terminal A.

   In Terminal B, run:

   curl -s http://127.0.0.1:4723/status
   

   First confirm /status responds successfully.

   Then confirm startup/readiness from server logs and ensure the Available drivers: block contains chromium (for example: - chromium@<version> (automationName 'Chromium')). If startup banner logs are not available in your terminal integration, use this fallback verification path:

   • appium driver list --installed --json includes chromium
   • /status reports server readiness

   After smoke validation, clean up the running Appium server:

   • In Terminal A, stop the server with Ctrl+C.
   • Verify no leftover Appium server process (Terminal B, macOS/Linux):

     pgrep -fl "appium.*server" || echo "no appium server process"
     

     If pgrep output appears to match only the check command itself, run a stricter verification:

     if ps -C node -o pid=,args= | grep -E 'appium.*server' > /dev/null; then
      ps -C node -o pid=,args= | grep -E 'appium.*server'
     else
      echo "no appium server process"
     fi
     

   • Verify no leftover Appium server process (Terminal B, Windows PowerShell):

     if (Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -match 'appium.*server' }) {
      Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -match 'appium.*server' } | Select-Object ProcessId, Name, CommandLine
     } else {
      "no appium server process"
     }
     

8. Agent completion criteria Mark the skill complete only when all are true:
   • appium driver list --installed --json includes chromium (fallback to appium driver list --installed if --json is unsupported)
   • appium -v succeeds and is Appium 3.x
   • active Node/npm versions satisfy appium and appium-chromium-driver engines
   • if supported, appium driver doctor chromium reports 0 required fixes needed (optional warnings are allowed)
   • if unsupported, result explicitly marks doctor status as not-supported
   • if no chromedriver binary was present initially and no pinned version was requested, task result includes successful execution of appium driver run chromium install-chromedriver
   • if Microsoft Edge automation was explicitly requested, task result includes installed Edge version, msedgedriver --version output, and the absolute path intended for appium:executable
   • task result includes browser availability check and the selected browser target (chrome, chromium, or msedge)
   • if optional browser setup was requested, task result includes browser install command(s) used and the post-install browser detection output
   • /status check returns a successful status response (curl on macOS/Linux, Invoke-RestMethod retry loop recommended on Windows)
   • Appium server logs show startup/readiness successfully after the status check, or readiness is confirmed by /status plus JSON driver listing that includes chromium
   • if logs are available, Available drivers: includes a chromium entry
   • Appium smoke-test server process is cleanly stopped after validation

Constraints

• Use global npm/Appium commands as the default execution mode.
• Use npx appium only if the user explicitly asks for local execution.
• Treat optional doctor warnings as non-blocking.
• Ask before installing optional dependencies or browser packages.
• Prefer deterministic CLI checks over assumptions.
• If elevated privileges are required, pause and provide exact commands for the user to run.
• Do not claim success until compatibility checks and smoke-test checks are green.