> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spurtest.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Override URLs

> Redirect tests to a different URL at runtime without changing your environment configuration.

## Overview

Override URL lets you redirect your tests to a different target URL when triggering a run — without editing your environment settings. This is especially useful in CI/CD pipelines where you want to test against a deploy preview, feature branch URL, or a different environment than the one configured in Spur.

For example, your environment might be configured to point at `https://staging.myapp.com`, but on a pull request you want to test the Vercel preview deploy at `https://my-app-pr-42.vercel.app`. Override URL handles this without any permanent configuration changes.

## How it works

Override URLs are passed as a JSON object when triggering a run via the API or webhook. The object has two optional fields:

| Field     | Type   | Description                                                                                                                                                                     |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `domains` | object | A mapping of environment domains to their replacement URLs. Spur matches the environment's configured domain against the keys and uses the corresponding value as the override. |
| `default` | string | A fallback URL used when no entry in `domains` matches the environment's domain.                                                                                                |

When a test starts, Spur resolves the override in this order:

1. Check each key in `domains` for a match against the environment's configured domain
2. If no match is found, fall back to `default`
3. If neither matches, the test runs against the original environment URL

When an override matches, Spur replaces the **origin** (scheme + host) of the configured URL with the override URL's origin. The original path, query parameters, and fragment are preserved. If the override URL includes a path, it is prepended to the original path.

## The `domains` option

Use `domains` when your test plan spans multiple environments and you need to override specific ones. Each key is a domain (or full origin) that Spur will match against your environment configuration.

```json theme={null}
{
  "override_urls": {
    "domains": {
      "staging.myapp.com": "https://my-app-pr-42.vercel.app",
      "api-staging.myapp.com": "https://api-pr-42.myapp.com"
    }
  }
}
```

Domain matching is flexible — keys can be:

* A bare hostname: `staging.myapp.com`
* A full origin with scheme: `https://staging.myapp.com`

Make sure the key matches your environment's configured domain exactly, including the `www.` prefix if present.

<Note>
  If your test plan only uses a single environment, the `default` option is simpler. Use `domains` when you need to override different environments with different URLs.
</Note>

## The `default` option

Use `default` when you want all tests to redirect to a single URL, regardless of which environment is configured. This is the simplest option and works well for single-environment test plans.

```json theme={null}
{
  "override_urls": {
    "default": "https://my-app-pr-42.vercel.app"
  }
}
```

You can also combine both options. Spur checks `domains` first and falls back to `default`:

```json theme={null}
{
  "override_urls": {
    "domains": {
      "api-staging.myapp.com": "https://api-pr-42.myapp.com"
    },
    "default": "https://my-app-pr-42.vercel.app"
  }
}
```

In this example, tests targeting `api-staging.myapp.com` use the API-specific override, while all other environments fall back to the Vercel preview URL.

## Using override URLs in CI/CD

### Via webhook

Pass `override_urls` in the request body when calling the Spur webhook:

```bash theme={null}
curl -X POST \
  -H "Content-Type: application/json" \
  -H "SPUR_GITHUB_KEY: <YOUR_API_KEY>" \
  -d '{
    "override_urls": {
      "default": "https://my-app-pr-42.vercel.app"
    }
  }' \
  "https://app.spurtest.com/api/webhook"
```

### In a GitHub Actions workflow

You can dynamically set the override URL using the deploy preview URL from your hosting provider:

```yaml theme={null}
- name: Run Spur Tests
  run: |
    curl -X POST \
      -H "Content-Type: application/json" \
      -H "SPUR_GITHUB_KEY: ${{ secrets.SPUR_API_KEY }}" \
      -d "{\"override_urls\": {\"default\": \"${{ steps.deploy.outputs.preview_url }}\"}}" \
      "https://app.spurtest.com/api/webhook"
```

## Examples

### Test a Vercel preview deploy

Your environment is set to `https://staging.myapp.com`. A PR creates a preview at `https://my-app-git-feature-login.vercel.app`.

```json theme={null}
{
  "override_urls": {
    "default": "https://my-app-git-feature-login.vercel.app"
  }
}
```

A test that would normally hit `https://staging.myapp.com/dashboard` now runs against `https://my-app-git-feature-login.vercel.app/dashboard`.

### Override multiple environments

Your test plan runs against both a frontend (`app.mysite.com`) and an API (`api.mysite.com`). Your PR has separate preview deploys for each.

```json theme={null}
{
  "override_urls": {
    "domains": {
      "app.mysite.com": "https://app-pr-99.mysite.dev",
      "api.mysite.com": "https://api-pr-99.mysite.dev"
    }
  }
}
```

### Override with a path prefix

Your preview environment serves the app under a subpath like `/preview/pr-42/`.

```json theme={null}
{
  "override_urls": {
    "default": "https://preview.myapp.com/preview/pr-42"
  }
}
```

A test targeting `https://staging.myapp.com/dashboard` now runs against `https://preview.myapp.com/preview/pr-42/dashboard`.