Ranger Feature Review

https://docs.ranger.net/
Admin
Ranger Feature Review is an AI QA platform that automatically verifies UI features in a real browser...
Tokens:13,289
Snippets:145
Trust Score:7.4
Update:7 months ago
Show doc for...
Tokens:
Raw
### Run Ranger Setup

Source: https://docs.ranger.net/getting-started/quickstart

Initiates the interactive setup process for Ranger from the project's root directory. This command guides the user through authentication, browser installation, plugin configuration, skill installation, and profile setup.

```bash
ranger setup
```

--------------------------------

### Install and Setup Ranger CLI

Source: https://docs.ranger.net/getting-started/agent-quickstart

Installs the Ranger CLI globally and sets up the agent with a provided API token and scope. It handles authentication, Chromium installation, plugin/skills installation, and profile creation.

```bash
npm install -g @ranger-testing/ranger-cli
ranger setup $RANGER_TOKEN --scope user --url http://localhost:3000
```

--------------------------------

### Run Ranger Setup with OpenCode

Source: https://docs.ranger.net/getting-started/quickstart-opencode

Initiates the Ranger setup process with the OpenCode integration. This command is run from the project root and guides the user through interactive configuration steps.

```bash
ranger setup --opencode

```

--------------------------------

### Install Project Dependencies with npm

Source: https://docs.ranger.net/reference/background-agents-and-ci

Installs all project dependencies defined in the package.json file using npm. This is a standard step in setting up a Node.js project for execution.

```bash
npm install
```

--------------------------------

### Install Ranger CLI using npm

Source: https://docs.ranger.net/getting-started/quickstart-opencode

Installs the Ranger testing command-line interface globally using npm. Ensure Node.js 18 or later is installed.

```bash
npm install -g @ranger-testing/ranger-cli

```

--------------------------------

### Authenticate Ranger CLI and Install Chromium

Source: https://docs.ranger.net/reference/background-agents-and-ci

Sets the Ranger API token as an environment variable and then uses the `ranger setup` command to authenticate and install the Playwright Chromium browser. This is crucial for browser automation.

```bash
export RANGER_CLI_TOKEN=<your-token>
ranger setup $RANGER_CLI_TOKEN
```

--------------------------------

### Install Ranger Skills

Source: https://docs.ranger.net/getting-started/quickstart

Asks the user if they want to install Ranger skills, which are essential for teaching the AI coding agent how to use Ranger for feature reviews and verifications. Responding 'Y' installs markdown files into the `.claude/skills/` directory.

```bash
Would you like to install skills? (Y/n)
```

--------------------------------

### Install Ranger CLI and Coding Agent

Source: https://docs.ranger.net/reference/background-agents-and-ci

Installs the Ranger CLI globally using npm. It also shows how to install a specific coding agent, such as Claude Code, using npm. Ensure Node.js and npm are installed.

```bash
npm install -g @ranger-testing/ranger-cli

# Plus your coding agent, e.g.:
npm install -g @anthropic-ai/claude-code
```

--------------------------------

### Install Ranger Skills

Source: https://docs.ranger.net/reference/background-agents-and-ci

Installs Ranger skill files using the `ranger skillup` command. These skills teach the coding agent how to perform tasks like creating feature reviews and running verifications. Skills are placed in `.claude/skills/`.

```bash
ranger skillup
```

--------------------------------

### Install Playwright Chromium

Source: https://docs.ranger.net/getting-started/quickstart

Prompts the user to install the required version of Playwright's Chromium browser, which is used by Ranger for running browser verifications. Responding 'Y' will proceed with the installation.

```bash
The required version of the Playwright Chromium browser is not installed. Install it now? (Y/n)
```

--------------------------------

### Ranger Setup with Authentication Token

Source: https://docs.ranger.net/getting-started/quickstart-opencode

Provides an alternative method for setting up Ranger in a CI environment by passing an authentication token directly. The token can be obtained from the Ranger Dashboard.

```bash
ranger setup --opencode [token]

```

--------------------------------

### Configure Claude Code Plugin Location

Source: https://docs.ranger.net/getting-started/quickstart

Presents options for installing the Claude Code plugin. Users can choose to install it for their user profile (available in all projects) or for the specific project (shared via git).

```bash
Where should the plugin be installed?
  > User (available in all your projects)
    Project (shared with team via git)
```

--------------------------------

### Ranger CLI Non-interactive Setup

Source: https://docs.ranger.net/reference/cli-overview

Demonstrates non-interactive setup for the Ranger CLI, allowing for programmatic configuration of scope, URL, and skipping certain steps like Chromium installation.

```bash
ranger setup $TOKEN --scope project --url http://localhost:3000
```

--------------------------------

### Setup Virtual Display for Headless Browser on Linux

Source: https://docs.ranger.net/reference/background-agents-and-ci

Installs and configures Xvfb (X virtual framebuffer) on Linux systems to provide a virtual display environment for headless browsers like Chromium. This is required when running Ranger in environments without a physical display server.

```bash
apt-get install -y xvfb
Xvfb :99 -screen 0 1920x1080x24 &
export DISPLAY=:99
```

--------------------------------

### Ranger CLI Setup Commands

Source: https://docs.ranger.net/reference/cli-overview

Provides an overview of Ranger CLI setup commands, including interactive setup, login, status checking, updates, and project cleanup.

```bash
ranger setup
ranger login
ranger status
ranger update
ranger clean
```

--------------------------------

### Setup Ranger without Profile

Source: https://docs.ranger.net/getting-started/agent-quickstart

Sets up Ranger with a project scope without creating an immediate profile. A profile can be added later when the application is running, suitable for CI environments where profiles are managed separately.

```bash
ranger setup $RANGER_TOKEN --scope project
ranger profile add local --url http://localhost:3000  # later
```

--------------------------------

### GitHub Actions Workflow for Ranger PR Verification

Source: https://docs.ranger.net/reference/background-agents-and-ci

A GitHub Actions workflow that automates pull request verification using Ranger CLI and Claude Code. It checks out the repository, installs dependencies, sets up Ranger and Claude Code, and runs a verification process, posting results as a PR comment. Requires RANGER_CLI_TOKEN and ANTHROPIC_API_KEY secrets.

```yaml
name: Ranger PR Verification

on:
    pull_request:
        types: [opened, synchronize, reopened]
    workflow_dispatch:
        inputs:
            pr_number:
                description: 'PR number to verify (optional, uses current branch if empty)'
                required: false
                type: string

env:
    HUSKY: 0

jobs:
    verify:
        name: Ranger PR Verification
        runs-on: ubuntu-latest
        permissions:
            contents: read
            pull-requests: write


        steps:
            - name: Checkout repository
              uses: actions/checkout@v4
              with:
                  fetch-depth: 0


            - name: Setup Node.js
              uses: actions/setup-node@v4
              with:
                  node-version: '20'


            - name: Install dependencies
              run: npm install


            - name: Install system dependencies
              run: |
                  sudo apt-get update
                  sudo apt-get install -y xvfb


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


            - name: Setup Ranger CLI
              env:
                  RANGER_CLI_TOKEN: ${{ secrets.RANGER_CLI_TOKEN }}
              run: ranger setup ${{ secrets.RANGER_CLI_TOKEN }}


            - name: Activate CI profile
              run: ranger profile use preview


            - name: Install Ranger skills
              env:
                  RANGER_CLI_TOKEN: ${{ secrets.RANGER_CLI_TOKEN }}
              run: ranger 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 Ranger verification
              env:
                  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
                  RANGER_CLI_TOKEN: ${{ secrets.RANGER_CLI_TOKEN }}
                  DISPLAY: ':99'
                  GH_TOKEN: ${{ github.token }}
              run: |
                  Xvfb :99 -screen 0 1920x1080x24 &
                  export DISPLAY=:99
                  sleep 2


                  claude --print "Look at the git diff for this branch against main. Use the /ranger skill to create a feature review from the changes and verify each scenario. Post results as a PR comment using gh."
              timeout-minutes: 30

```

--------------------------------

### Set Local Application URL

Source: https://docs.ranger.net/getting-started/quickstart

Prompts the user to enter the URL of their locally running web application. Ranger uses this URL to access the app for verification and saves session cookies after a login verification.

```bash
What is the URL of your running app? (http://localhost:3000)
```

--------------------------------

### Run Ranger with Claude Code for Feature Build and Verify

Source: https://docs.ranger.net/reference/background-agents-and-ci

Instructs Claude Code to implement a feature (e.g., dark mode toggle) and then use the Ranger skill to create a feature review and verify the implementation end-to-end in the browser.

```bash
claude --print "Add a dark mode toggle to the settings page. \ 
  After implementing, use the /ranger skill to create a feature review \ 
  and verify that the toggle works end-to-end in the browser."
```

--------------------------------

### Clone Repository with Full Git History

Source: https://docs.ranger.net/reference/background-agents-and-ci

Clones a Git repository including its complete history. This is necessary for Ranger to generate accurate diffs and track changes effectively within CI or background agent workflows.

```bash
git clone --depth=0 <repo>
```

--------------------------------

### Enable Ranger in OpenCode Session

Source: https://docs.ranger.net/getting-started/quickstart-opencode

Instructs the OpenCode agent to enable Ranger features for the current session. This activation is typically done once per branch.

```bash
enable ranger

```

--------------------------------

### Configure OpenCode for Ranger Plugin

Source: https://docs.ranger.net/getting-started/quickstart-opencode

Illustrates the JSON configuration block added to `opencode.json` to integrate the Ranger OpenCode plugin. This enables Ranger's functionality within the OpenCode workflow.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@ranger-testing/opencode-plugin"]
}

```

--------------------------------

### Configure Claude Code Agent Permissions

Source: https://docs.ranger.net/reference/background-agents-and-ci

Configures permissions for the Claude Code agent by creating a `.claude/settings.local.json` file. This grants necessary permissions like running bash commands, reading files, and globbing.

```json
{
  "permissions": {
    "allow": [
      "Bash(*)",
      "Read(*)",
      "Glob(*)",
      "Grep(*)"
    ],
    "deny": []
  }
}
```

--------------------------------

### Update Encrypted Ranger Profile

Source: https://docs.ranger.net/reference/background-agents-and-ci

Updates the local encrypted Ranger profile using `ranger profile update preview`. The updated `.ranger/ci/preview/auth.json.enc` file should then be committed to git.

```bash
ranger profile update preview
```

--------------------------------

### Start Browser Agent for Scenario Verification

Source: https://docs.ranger.net/reference/cli-overview

This command spawns a browser agent to test the scenarios defined for the active feature review. The agent interacts with the UI, captures screenshots, and provides a verification status.

```bash
ranger go
```

--------------------------------

### Configure Ranger CLI for Vercel Preview Environments

Source: https://docs.ranger.net/reference/background-agents-and-ci

This command configures the Ranger CLI to use a custom header for bypassing Vercel's Deployment Protection. It requires a bypass token generated from Vercel project settings.

```bash
ranger profile config set preview header.x-vercel-protection-bypass '<your-bypass-token>'
```

--------------------------------

### Add Local Profile for Ranger

Source: https://docs.ranger.net/getting-started/quickstart-opencode

Command to add a local profile for Ranger, typically used when the application is running locally. This involves specifying the application's URL and potentially logging in.

```bash
ranger profile add local

```

--------------------------------

### Configure Dynamic Base URL for Ranger Profile

Source: https://docs.ranger.net/reference/background-agents-and-ci

Sets a dynamic base URL for the 'preview' Ranger profile using an environment variable. This allows Ranger to adapt to changing deployment URLs, such as Vercel preview URLs or Heroku review apps, by resolving the environment variable at runtime.

```bash
ranger profile config set preview baseUrl '${PREVIEW_URL}'
```

--------------------------------

### Activate Encrypted Ranger Profile

Source: https://docs.ranger.net/reference/background-agents-and-ci

Activates a specific encrypted profile for Ranger CLI using the `ranger profile use` command. This decrypts the `auth.json.enc` file at runtime using the `RANGER_CLI_TOKEN`.

```bash
ranger profile use preview
```

--------------------------------

### Add Ranger Encrypted Profile for CI

Source: https://docs.ranger.net/reference/background-agents-and-ci

Creates a new Ranger profile named 'preview' for CI environments. This command initiates a browser session to capture authentication cookies, which are then encrypted and saved locally. The profile is essential for Ranger to authenticate within the target hosted environment.

```bash
ranger profile add preview --ci
```

--------------------------------

### Enable Ranger in Claude Code

Source: https://docs.ranger.net/getting-started/quickstart

Activates Ranger's integration within a Claude Code session using a slash command. This command enables Ranger's hooks for the current session and typically persists across sessions on a given branch.

```bash
/ranger:enable
```

--------------------------------

### Configure Custom Headers for Ranger Profile

Source: https://docs.ranger.net/reference/background-agents-and-ci

Configures a custom header, specifically 'Authorization', for the 'preview' Ranger profile using an environment variable. This enables dynamic injection of authentication tokens or other sensitive information at runtime, enhancing security and flexibility.

```bash
ranger profile config set preview header.Authorization '${AUTH_TOKEN}'
```

--------------------------------

### Commit Ranger Encrypted Profile to Git

Source: https://docs.ranger.net/reference/background-agents-and-ci

Adds the Ranger encrypted profile directory to Git staging and commits it with a descriptive message. This ensures that the encrypted authentication state and settings are version-controlled and available across different environments.

```bash
git add .ranger/ci/
git commit -m "Add Ranger encrypted profile"
```

--------------------------------

### Run Ranger with Claude Code for CI Bug Bash

Source: https://docs.ranger.net/reference/background-agents-and-ci

Invokes Claude Code in non-interactive mode to perform a bug bash on a PR's changes. It uses the Ranger skill to create a feature review from UI changes and verify scenarios, posting results as a PR comment via `gh`.

```bash
claude --print "Look at the git diff for this branch against main. \ 
  Use the /ranger skill to create a feature review from the UI changes \ 
  and verify each scenario. Post results as a PR comment using gh."
```

--------------------------------

### Create a New Feature Review with Description and Scenarios

Source: https://docs.ranger.net/reference/cli-overview

This command creates a new feature review, allowing you to specify a name, description, and scenarios for testing. It automatically detects your git repository and branch, making the review active immediately.

```bash
ranger create "Dark Mode Toggle" \
  -d "Add dark mode support to settings page" \
  -c "User opens settings, toggles dark mode, and the page switches themes"
```

--------------------------------

### Ranger CLI Custom Login Instructions

Source: https://docs.ranger.net/reference/cli-overview

Shows how to set custom login instructions for a Ranger profile to handle specific authentication flows, including the use of environment variables.

```bash
ranger profile config set local loginInstructions "Navigate to http://localhost:3000/api/debug-auth?email=test@example.com. Copy the token from the JSON response. Run in the browser console: localStorage.setItem('auth_token', '<the-token>'). Refresh the page."
ranger profile config set local loginInstructions "Navigate to ${BASE_URL}/api/debug-auth?email=${TEST_USER_EMAIL} to obtain a session token."
```

--------------------------------

### Ranger CLI Profile Configuration Commands

Source: https://docs.ranger.net/reference/cli-overview

Details commands for configuring profile settings such as headless mode, user agent, storage state, CDP endpoint, and custom headers.

```bash
ranger profile config set local headless true
ranger profile config set ci header.Authorization '${AUTH_TOKEN}'
ranger profile config set my-electron-app cdpEndpoint http://localhost:9222
```

--------------------------------

### Configure Custom Login Instructions for Ranger Profile

Source: https://docs.ranger.net/concepts/profiles

This command configures custom login instructions for a Ranger profile. It specifies a URL to navigate to for authentication and how to store the obtained token in local storage. This is useful for applications with short-lived authentication tokens.

```bash
ranger profile config set local loginInstructions "Navigate to http://localhost:3000/api/debug-auth?email=test@example.com. Copy the token from the JSON response. Run in the browser console: localStorage.setItem('auth_token', '<the-token>'). Refresh the page."
```

--------------------------------

### List Feature Reviews on Current Git Branch

Source: https://docs.ranger.net/reference/cli-overview

This command lists all feature reviews associated with the current git branch. It helps in managing and resuming work on specific feature reviews.

```bash
ranger list --current-branch
```

--------------------------------

### Ranger CLI Profile Management Commands

Source: https://docs.ranger.net/reference/cli-overview

Lists commands for managing Ranger CLI profiles, including adding, switching, listing, updating, and encrypting authentication details.

```bash
ranger profile add <name>
ranger profile use <name>
ranger profile ls
ranger profile update <name>
ranger profile encrypt-auth <name>
```

--------------------------------

### Encrypt Authentication Profile for Secure Storage

Source: https://docs.ranger.net/reference/cli-overview

This command encrypts a profile's auth.json file, enabling secure storage of authentication credentials, particularly for CI/CD pipelines.

```bash
ranger profile encrypt-auth <profile>
```

--------------------------------

### Resume an Existing Feature Review Session

Source: https://docs.ranger.net/reference/cli-overview

This command sets a specific feature review as active, resuming its session. This is useful for continuing work on a previously created feature review.

```bash
ranger resume feat_abc123
```

--------------------------------

### Add Ranger Profile Non-Interactively

Source: https://docs.ranger.net/concepts/profiles

These commands demonstrate how to add a Ranger profile non-interactively. You can specify the URL directly, bypass reachability checks with `--force`, or skip the browser authentication step entirely with `--skip-auth`.

```bash
ranger profile add local --url http://localhost:3000
```

```bash
ranger profile add local --url http://localhost:3000 --force       # skip reachability check
```

```bash
ranger profile add local --url http://localhost:3000 --skip-auth   # no browser auth
```

--------------------------------

### Invoke Ranger Skill in Claude Code

Source: https://docs.ranger.net/reference/cli-overview

This slash command invokes the main Ranger skill within Claude Code. It can be used to create, verify, or manage feature reviews directly from the Claude Code interface.

```bash
/ranger
```

--------------------------------

### Disable Ranger Hooks in Claude Code

Source: https://docs.ranger.net/reference/cli-overview

This slash command disables Ranger hooks for the current session in Claude Code, stopping Ranger's integration with the coding environment.

```bash
/ranger:disable
```
Tokens:
Raw