Managing Profiles

Two concepts keep your agent focused: scenarios and profiles.

Scenarios describe what to test. Profiles describe where to test and how to access it.

Architecture of Profiles

Profiles are made up of three components:

• endpoint
• auth
• settings

The endpoint is where the test runs. Auth and settings define how the browser verification agent gets in.

You can create as many profiles as you need.

Endpoint

Endpoints keep Ranger’s browser agent focused on the environment you want to test. For local development, this is usually a localhost host and port where your app is running. The browser agent is restricted to this endpoint, which helps prevent your coding agent from seeing a staging or prod URL in the codebase and attempting to test that instead.

In some cases, the goal is to verify behavior in a non-local environment. A profile can be set up for a remote endpoint as well.

The endpoint needs to include a URL protocol (usually http:// or https://).

Example endpoints:

• http://localhost:3000
• https://staging.example.com

Auth

Many testing scenarios require a logged-in user. Asking you to log in every run defeats the purpose of autonomous testing. In some cases, basic username/password auth could live in a .env file, but many apps use SSO, 2FA, or magic link login.

Instead, Ranger opens a headed browser when you create a profile. You log in once, and Ranger saves the cookies and session state for each test run. This handles more complicated auth reliably.

Cookies expire, so profile auth goes stale over time. For most apps this is fine during a coding session. For background agents and CI, plan to refresh auth when it expires.

Settings

Settings handle other details that may be important for an effective testing setup. In some cases, setting a specific userAgent or headers helps with bot protection or custom auth.

headless can also be configured and determines whether testing happens in a headed (visible) or headless (without a GUI or open window) browser. Headed can be helpful for observing the agent verification firsthand.

Active Profile

A single profile is set as active and used as the default for ranger go, unless you pass another profile via --profile. Use ranger profile use <name> to switch and ranger profile ls to see what is available.

Local vs CI Profiles

Local profiles are meant for day-to-day development by a single user and the auth is stored in plaintext. This is convenient and fast, but not safe to share. They’re added to a ranger-specific .gitignore to prevent them from being committed to version control.

CI profiles are meant for pipelines and other shared usages. The auth file is encrypted and safe to commit. Use the --ci flag when adding the profile and in CI or the remote environment, running ranger setup [token] will decrypt it.

Adding and Updating Profiles

Adding

1. Run ranger profile add <name>.
2. Enter the base URL when prompted.
3. A browser opens. Log in to the account you want the agent to use.
4. Close the browser to save the profile.

Ranger sets the new profile as active. Your app should be running before you start.

Updating

Update a profile when auth expires or you need a different user.

Run ranger profile update <name>. Ranger opens a browser with your current session if available. Log in again if needed, then close the browser to save the new auth. For CI profiles, this writes a new encrypted auth file.

Workflows with Multiple Profiles

Testing interconnected apps

One use of multiple profiles is to handle feature reviews that involve scenarios in different but connected applications.

For instance, if your customer-facing app runs on localhost:3000 and your internal tool runs on localhost:3001, you could set up a profile for each of those endpoints and then tell your coding agent to use a specific one for each scenario.

$ ranger profile add customer-app

? What is the URL of your running app? http://localhost:3000

Saving authentication state...
✓ Created settings
  Set active profile: customer-app

  Profile "customer-app" configured

$ ranger profile add internal-app

? What is the URL of your running app? http://localhost:3001

Saving authentication state...
✓ Created settings
  Set active profile: internal-app

  Profile "internal-app" configured

Testing with different user types

Another use of multiple profiles is to run scenarios against different types of users.

As an example, if your app has free, paid, and enterprise customers and you’re adding a feature that affects all of them, create a profile for each user type. All profiles can point at the same endpoint. Use the Authentication Setup step in the browser to log into a different account for each.

Prompt your coding agent to use each of the profiles for a different scenario so that you can see each one in the Feature Review UI.