Skip to main content

​
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:
FieldTypeDescription
domainsobjectA 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.
defaultstringA 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. 
{
  "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.
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.

​
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. 
{
  "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: 
{
  "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: 
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: 
- 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. 
{
  "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. 
{
  "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/. 
{
  "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.