npm package: @ranger-testing/run-test
Description: Run Ranger tests against a local development server
Latest version: 0.0.5

# Running Ranger tests locally

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

## Getting Started

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

### 1. Install browser

```bash
ranger-test install
```

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

### 2. Authenticate

```bash
ranger-test login
```

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

### 3. Install the skill

```bash
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:

```bash
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:

```bash
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

```bash
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:

```bash
ranger-test env
```

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

```bash
ranger-test env --create
```

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

```bash
# .env.ranger
TEST_EMAIL=local-dev@example.com
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):

```bash
ranger-test login <token>
```

Or set the `RANGER_API_TOKEN` environment variable — no login needed:

```bash
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

```bash
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:

```bash
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

```yaml
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 |