Running Ranger tests locally

Run Ranger's automated tests against your locally-running application.

Getting Started

npm install -g @ranger-testing/run-test

1. Install browser

ranger-test install

This downloads the correct version of Chromium for running tests locally.

2. Authenticate

ranger-test login

This opens your browser to log in, then stores an API key locally.

3. Install the skill

ranger-test skillup

This installs the ranger-test skill for Claude Code so your coding agent knows how to run tests.

Use --agent to install for a different coding agent:

ranger-test skillup --agent=claude   # default
ranger-test skillup --agent=cursor
ranger-test skillup --agent=codex

Use --scope to control where the skill is installed:

ranger-test skillup --scope user     # default (~/.claude/skills, ~/.cursor/rules, etc.)
ranger-test skillup --scope project  # ./.claude/skills, ./.cursor/rules, etc.

4. Use your coding agent

Ask Claude to run tests against your local app:

"/ranger-test Run the login tests against localhost:3000"

The agent will use ranger-test list to find available tests, then ranger-test run to execute them through a tunnel to your local machine.

5. Update

ranger-test update

Checks npm for the latest version, installs it, and reinstalls skills wherever they are already installed (across all agents and scopes).

Environment Variables

Tests use environment variables configured in your Ranger org settings (e.g. TEST_EMAIL, TEST_PASSWORD). To see what's configured:

ranger-test env

To create a .env.ranger template with all available variables:

ranger-test env --create

Uncomment and fill in the values you want to override, then run tests:

# .env.ranger
[email protected]
API_BASE=http://localhost:3000/api

Local overrides take precedence over org-configured values. The CLI logs which variables are being overridden on each run.

Running tests remotely

Use run-remote to trigger test runs against a preview or deployed environment. Tests execute on Ranger's infrastructure — no local browser or tunnel required.

Authentication

Authenticate with a token directly (no interactive browser flow):

ranger-test login <token>

Or set the RANGER_API_TOKEN environment variable — no login needed:

export RANGER_API_TOKEN=<token>

The token is resolved in this order: RANGER_API_TOKEN env var > RANGER_CLI_TOKEN env var > ~/.ranger/test-cli.txt (written by ranger-test login).

Usage

ranger-test run-remote -u https://preview-abc123.example.com --ids 532a218c9140ef48,a03bf219c7e14d92

The command queues the run and returns immediately with a dashboard link.

GitHub parameters

GitHub owner, repo, and PR number are resolved in this order:

1. CLI flags (--gh-owner, --gh-repo, --gh-pr-number)
2. GitHub Actions environment variables (GITHUB_REPOSITORY_OWNER, GITHUB_REPOSITORY, GITHUB_REF)
3. Auto-detected from the git remote URL

This means run-remote works out of the box in GitHub Actions with no extra flags, and locally it picks up owner/repo from your git remote.

PR integration

Pass --pr-comment to post test results as a comment on the associated PR:

ranger-test run-remote -u https://preview-abc123.example.com --pr-comment --gh-pr-number 42

Use your coding agent

Ask Claude to run tests against your preview deployment:

"/ranger-test-remote Run tests against https://preview-abc123.example.com"

The agent will use ranger-test list to find available tests, match them to your code changes, then ranger-test run-remote to kick off the relevant tests on Ranger's infrastructure.

Example GitHub Actions workflow

name: Ranger Tests on Preview

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  ranger-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Claude Code and Ranger Test CLI
        run: npm install -g @anthropic-ai/claude-code @ranger-testing/run-test

      - name: Authenticate Ranger
        run: ranger-test login ${{ secrets.RANGER_API_TOKEN }}

      - name: Install Ranger skills
        run: ranger-test skillup

      - name: Configure Claude Code permissions
        run: |
          mkdir -p .claude
          cat > .claude/settings.local.json << 'EOF'
          {
            "permissions": {
              "allow": [
                "Bash(*)",
                "Read(*)",
                "Glob(*)",
                "Grep(*)"
              ],
              "deny": []
            }
          }
          EOF

      - name: Run tests against preview
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          RANGER_API_TOKEN: ${{ secrets.RANGER_API_TOKEN }}
        run: |
          claude --print "Examine the PR diff and run relevant tests against ${{ env.PREVIEW_URL }} using /ranger-test-remote"
        timeout-minutes: 10

Replace ${{ env.PREVIEW_URL }} with your preview environment URL (e.g. from a previous deployment step). GitHub owner, repo, and PR number are auto-detected from the Actions environment.

Commands

| Command | Description | |---------|-------------| | ranger-test install | Install required browser (Chromium) | | ranger-test login | Authenticate with Ranger (interactive) | | ranger-test login <token> | Store an API token directly (for CI) | | ranger-test list | List available tests | | ranger-test list -v | List tests with descriptions | | ranger-test env | Show org environment variables (obfuscated) | | ranger-test env --create | Create a .env.ranger template | | ranger-test run -u <url> | Run all tests against a local URL | | ranger-test run -u <url> --ids <id1>,<id2> | Run specific tests | | ranger-test run -u <url> --project <name> | Run a Playwright project | | ranger-test run -u <url> --headed | Run with visible browser | | ranger-test run -u <url> -v | Show individual test results | | ranger-test run-remote -u <url> | Run all tests remotely against a deployed URL | | ranger-test run-remote -u <url> --ids <id1>,<id2> | Run specific tests remotely | | ranger-test run-remote -u <url> --labels <l1>,<l2> | Run tests filtered by label | | ranger-test run-remote -u <url> --pr-comment | Run and post results as a PR comment | | ranger-test run-remote --gh-owner <owner> --gh-repo <repo> | Run with explicit GitHub params | | ranger-test skillup | Install the skill for Claude Code (~/.claude) | | ranger-test skillup --agent=cursor | Install the skill for Cursor (~/.cursor) | | ranger-test skillup --agent=codex | Install the skill for Codex (~/.codex) | | ranger-test skillup --scope project | Install the skill at project level | | ranger-test update | Update to latest version and reinstall skills | | ranger-test clean | Remove ranger-test artifacts |