> ## Agent Instructions
> Spur is an AI-powered QA engineer that lets teams create and run automated end-to-end tests for web and mobile apps using natural language.
> When answering questions about Spur, cite the relevant page from docs.spurtest.com.
# Contact Us
Source: https://docs.spurtest.com/additional-resources/contact-us
Get in touch with the Spur team for support, questions, or feedback.
## Your Dedicated Account Manager
Every Spur account comes with a dedicated account manager. They are your primary point of contact for onboarding, technical questions, and ongoing support. If you are unsure who your account manager is, reach out to us at **[founders@tryspur.dev](mailto:founders@tryspur.dev)** and we will connect you.
## Direct Line of Communication
We keep communication fast and direct. Depending on your preference, you can reach us through:
Chat with us directly through Google Workspace for quick questions and async communication.
Message your account manager on WhatsApp for real-time support.
Join a shared Slack channel with the Spur team for collaborative support.
Reach out to us at **[founders@tryspur.dev](mailto:founders@tryspur.dev)** for any questions or requests.
## Other Resources
Visit spurtest.com to learn more about Spur.
Want a walkthrough of Spur? Book a demo with our team.
Follow us on LinkedIn for updates and to connect with the team.
# Deep Links
Source: https://docs.spurtest.com/additional-resources/deep-links
Use deep links in Spur to navigate directly to specific screens in your mobile app during testing.
Deep links are URLs that navigate directly to a specific screen within a mobile app, bypassing the normal navigation flow. Instead of tapping through multiple screens to reach a destination, a deep link takes you straight there.
The most common type is a **URI scheme** — a custom protocol registered by the app (e.g., `myapp://products/12345`). This is the primary method used in Spur.
## Why Use Deep Links in Tests?
* **Skip repetitive navigation** — Jump straight to the screen you want to test instead of tapping through five screens to get there.
* **Isolate test scope** — Test a specific feature without coupling to login and browsing flows.
* **Test deep link behavior** — Verify that your app correctly handles incoming deep links.
## How It Works
In native mobile tests, Spur triggers deep links using a [JavaScript injection](/authoring-tests/test-side-peek/step-types/javascript) step with the `[Deeplink]` label. You can add this step through the native commands UI in the test editor.
To find your app's URI scheme, ask your development team or check the app's configuration files (`Info.plist` on iOS, `AndroidManifest.xml` on Android).
## Example
This test deep links from the home screen directly to a product collection page:
```text theme={null}
Wait for the app to load
If "Sign In" is displayed, tap Sign In and log in. Otherwise, skip this step.
Navigate to the home page
Cached Action: [Deeplink] {{ window.location = 'myapp://collections/womens-shop-all'; }}
Wait 2 seconds
Verify that "Women's Shop All" is displayed
```
The URI scheme `myapp://` routes to the app, and the path `collections/womens-shop-all` tells it which screen to display.
Always add a **wait** or **verify** step after a deep link to give the app time to load the target screen.
## Best Practices
* Use the [recommended starting template](/getting-started/mobile-prompting#recommended-test-starting-template) to handle login and popups before triggering the deep link.
* Always verify the expected screen loaded after the deep link.
* If a test starts failing after an app update, check whether the URI scheme or path has changed.
## Related Resources
* [Mobile Prompting Guide](/getting-started/mobile-prompting) — Best practices for writing native mobile test steps
* [JavaScript Injection](/authoring-tests/test-side-peek/step-types/javascript) — The `Cached Action` step type used for deep links
# IP Whitelisting
Source: https://docs.spurtest.com/additional-resources/ip-whitelisting
Allow Spur agent to access your application by whitelisting our IP addresses.
## Why Whitelist Spur's IPs?
Spur runs automated browser tests against your application from our cloud infrastructure. If your staging, development, or production environment is behind a firewall, VPN, or IP-restricted access layer, you need to allow traffic from Spur's IP addresses so that tests can reach your application.
If Spur's IPs are not whitelisted, test runs will fail with connection or timeout errors because our test runners cannot reach your application.
## Spur IP Addresses
Contact the Spur team to get the current list of IP addresses you need to whitelist.
Reach out to the Spur team to request the IP addresses for your allowlist.
## How to Whitelist
The exact steps depend on where your application is hosted. Below are instructions for common providers.
Go to the [EC2 Console](https://console.aws.amazon.com/ec2/) and select **Security Groups** from the left sidebar.
Find and click the security group attached to your application's instance or load balancer.
Click **Edit inbound rules** and add a new rule:
* **Type:** HTTPS (port 443) or HTTP (port 80), depending on your setup
* **Source:** Custom, then enter each Spur IP address
* **Description:** Spur test runners
Click **Save rules**. Changes take effect immediately.
Go to the [VPC Firewall Rules](https://console.cloud.google.com/networking/firewalls) page in the Google Cloud Console.
Click **Create Firewall Rule** and configure:
* **Name:** `allow-spur-test-runners`
* **Direction:** Ingress
* **Targets:** Select the target tags or service accounts for your application
* **Source IP ranges:** Enter each Spur IP address
* **Protocols and ports:** Allow TCP on port 443 (and 80 if needed)
Click **Create**. The rule applies within a few seconds.
Go to **Network Security Groups** in the [Azure Portal](https://portal.azure.com/).
Click the NSG associated with your application's subnet or network interface.
Go to **Inbound security rules** and click **Add**:
* **Source:** IP Addresses
* **Source IP addresses:** Enter each Spur IP address (comma-separated)
* **Destination port ranges:** 443 (and 80 if needed)
* **Protocol:** TCP
* **Action:** Allow
* **Name:** `AllowSpurTestRunners`
Click **Add**. The rule takes effect shortly.
Most modern hosting platforms like Vercel, Netlify, and Cloudflare do not block incoming traffic by default. If you have configured IP-based access restrictions (such as Cloudflare Access or Vercel's IP allowlisting), add Spur's IP addresses to your allowlist through that platform's dashboard.
If you manage access control at the web server level, add Spur's IPs to your configuration.
**Nginx** — add inside your `server` or `location` block:
```nginx theme={null}
allow ;
allow ;
# Add all IPs provided by the Spur team
```
**Apache** — add inside your `` or `` block:
```apache theme={null}
Require ip
Require ip
# Add all IPs provided by the Spur team
```
Reload your web server after making changes.
## Verifying the Setup
After whitelisting, run a quick test from Spur to confirm connectivity:
Navigate to any existing test or create a new one that targets the environment behind your firewall.
Execute the test. If the first step (navigating to your URL) completes successfully, whitelisting is working.
If the test fails with a timeout or connection error:
* Confirm the correct IPs are whitelisted
* Check that the allowed ports match your application (443, 80, or a custom port)
* Verify there are no additional layers (VPN, WAF, CDN) that also require allowlisting
If your infrastructure uses a Web Application Firewall (WAF) in addition to network-level rules, you may need to add Spur's IPs to both the WAF allowlist and your firewall rules.
## What Spur Does NOT Access
Spur operates strictly at the browser/UI layer. We never touch the systems behind your application.
No access to your source code, repositories, or build systems.
No access to back-end systems, databases, or internal infrastructure.
Nothing beyond the browser/UI layer — no software is installed on your systems.
No customer PII is collected or stored beyond the test data you provide.
## Security Posture
Full details and reports available in our [**Trust Center**](https://app.vanta.com/tryspur.dev/trust/6bd89ygtkuvxrvbm0v6huw).
Easy to scope and to exclude from your analytics.
Data encrypted in transit and at rest; access limited to the surfaces you designate.
Access is revocable instantly, at any time, by you.
# Network & Console Monitoring
Source: https://docs.spurtest.com/additional-resources/network-console-monitoring
Use Log steps to assert against network requests and console logs during test execution.
The Log step lets you validate what happens behind the scenes during a test run. Instead of checking what the user sees on screen (that's what [Verify](/authoring-tests/test-side-peek/step-types/verify) does), Log steps assert against **network requests** and **browser console output** — giving you visibility into API calls, error messages, and other under-the-hood behavior.
You describe what you expect in plain language, and the Spur agent intelligently searches through the captured data to verify your assertion. It returns the matching evidence — the endpoint, a data snippet, and timestamp — so you can see exactly what it found.
To learn how to add a Log step to your tests, see the [Log Step](/authoring-tests/test-side-peek/step-types/log/log-assertions) guide.
## Understanding the Result
When a Log step completes, Spur expands the result to show exactly how it verified your assertion. Here's what each part means:
* **Reasoning** — The agent restates your assertion to confirm what it set out to verify.
* **Verification Analysis** — The agent breaks your assertion into a **primary subject** (the request or event type to find) and a **qualifier** (the specific condition to check within it). This is how the agent decides where to look and what to look for.
* **What I Found** — A detailed breakdown of the matching evidence, including the endpoint, request method, status code, URL parameters, and any relevant payload data. This is the raw proof that supports the result.
* **Conclusion** — A plain-language summary of whether the assertion passed or failed and why.
* **Examined requests** — A clickable badge linking to the specific network request the agent inspected. Click it to jump directly to the full request details in the Network Logs panel.
## Use Cases
### Event & Analytics Tracking
Analytics, tracking pixels, and third-party event calls break silently — they don't affect the UI, so regressions go unnoticed. Log steps let you confirm these events fire correctly during key user flows.
### Validate API Status Codes & Responses
The UI might show a success message even when the backend returns an error or unexpected data. Log steps let you check the actual API responses your application receives.
### Validate Request Payloads
Confirm that your application sends the correct data to the backend — not just that the form submitted successfully.
## What Data Is Available
During every test run, Spur captures all **network requests** and **browser console output** from your application. The Log step agent searches through this data to evaluate your assertions, and you can also inspect it directly from the test results view.
Every HTTP request and response, including:
* URL, method, and status code
* Request and response headers
* Request body (POST data)
* Response body
* Timing and duration
* Error details (HTTP and network errors)
All browser console output, including:
* Log messages (`console.log`, `console.warn`, `console.error`)
* JavaScript errors and stack traces
* Source file locations
* Timestamps
## Viewing Logs in Test Results
After a test run completes, you can inspect the raw network and console data directly from the results view.
### Network Logs
You can inspect the exact requests examined by the Spur agent by clicking the examined request in the step result.
You can filter network logs by status code, HTTP method, or URL pattern. Click any entry to see full request and response details including headers and body content.
### Console Logs
Console logs display the message type, timestamp, content, and source location. You can search and filter logs to find specific entries.
## Best Practices
### Writing Effective Assertions
Use a Verify step to check what the user sees, then follow it with a Log step to confirm the right data was sent and received. Together they give you full coverage — UI and backend in one test.
Mention the specific assertion you want to perform: network or console. For example, "Validate the payload for collect-tag contains event\_code" should specify whether the agent needs to look for it in the console output or the network requests. So this should be rewritten as "Validate in the console ..."
Keep each Log step focused on a single check. Instead of "confirm the API returned 200 and the tracking event fired," split that into two separate Log steps. This makes results easier to interpret and debug.
You don't need to know the exact request format, header names, or payload structure. Describe the behavior you expect and the agent will figure out where and how to look for it.
### When to Use Log Steps
Log steps are great for regression testing. Add them to your existing tests to make sure API behavior doesn't silently change between releases.
The UI might gracefully handle a 500 error or swallow a failed analytics call. Log steps surface these hidden issues that would otherwise go unnoticed.
Add Log steps to your most important user journeys — signup, form submissions, data updates, key workflows. These are the flows where a broken API call has real consequences.
Analytics, ad pixels, and third-party scripts break silently. Use Log steps to verify these calls fire on the right pages so you catch regressions early.
## Limitations
* **Logs are analyzed after capture, not in real-time.** The agent evaluates network and console data that has already been recorded during the test run. It does not monitor logs as they stream in.
* **Late-firing requests may not be captured.** If a network request or event fires after the test step has finished executing, it may not be included in the data the agent searches through. This can affect assertions on deferred or asynchronous calls that take a long time to complete.
## Troubleshooting
Make sure your assertion names the endpoint or event clearly. For example, instead of "Confirm the homepage event fired," try "Confirm the request to **/collect** contains **homepage** in the payload." Being specific about the endpoint helps the agent find the right request.
Try making your assertion more specific. Instead of "check the API response is correct," specify the exact endpoint, field, and expected value. A vague assertion could match unrelated data.
This usually means there's a real backend issue the UI is masking. Check the network logs panel in the test results to see the actual API responses.
Log steps are only available for web tests. If you're authoring a native/mobile test, this step type will not appear in the step menu.
# Spur for Data Science Teams
Source: https://docs.spurtest.com/additional-resources/spur-for-data-science-teams
Automate analytics event validation, tracking QA, and data quality monitoring — without writing code or inspecting DevTools manually.
If you work in data science, analytics, or marketing technology, you know the pain: every release cycle means hours of manually checking that tracking events fire correctly, payloads contain the right fields, and downstream data pipelines receive clean inputs. When something breaks, it often goes undetected for days or weeks — leading to bad dashboards, broken attribution, and lost revenue.
Spur automates this entire validation process. This guide explains how it works, why it matters, and how to get started — even if you have never automated anything before.
***
## The Problem You Are Solving
Analytics and tracking implementations break silently. Unlike a broken button or a crashed page, a missing tracking event produces no visible error. The user experience looks fine. But behind the scenes:
* Events stop firing after a code deploy
* Required fields disappear from payloads
* Data types change (string becomes number, casing shifts)
* Third-party pixels and affiliate tags get dropped
* UTM parameters are stripped during redirects
These failures are invisible to end users — but they corrupt your data, break attribution models, and undermine every decision made from that data.
### How Teams Typically Catch These Issues Today
```mermaid theme={null}
graph TD
A["Open Chrome DevTools"] --> B["Navigate to page / complete flow"]
B --> C["Search console or network tab for events"]
C --> D["Manually inspect each payload field"]
D --> E["Screenshot as evidence"]
E --> F["Cross-reference with analytics platform"]
F --> G["Repeat for every region, brand, browser, environment"]
G --> H["File a ticket if something is wrong"]
style A fill:#fee,stroke:#c33
style G fill:#fee,stroke:#c33
```
This process has fundamental limitations:
* **It does not scale.** A site with 30+ tracked events across multiple regions, brands, and browsers creates thousands of combinations to check.
* **It is error-prone.** Humans miss subtle changes — a field that switched from lowercase to uppercase, a value that went from `"12.99"` to `12.99`.
* **It is reactive.** Manual QA happens after deploys. Issues often reach production before anyone checks.
* **It consumes analyst time.** Every hour spent in DevTools is an hour not spent on actual data analysis and strategy.
***
## How Spur Automates This
Spur replaces the manual DevTools process with an automated browser agent. Here is how it works at a high level:
```mermaid theme={null}
graph LR
A["You define what to validate"] --> B["Spur opens a real browser"]
B --> C["Agent navigates your site like a real user"]
C --> D["All network traffic is captured automatically"]
D --> E["Agent validates payloads against your expectations"]
E --> F["Results: pass/fail with evidence"]
```
### What the Agent Actually Does
Spur launches a real Chrome or Safari browser — not a simulator. It behaves exactly like a user visiting your site, including cookies, consent banners, and third-party scripts.
The agent navigates to the right page, clicks through the flow (view a product, add to cart, complete checkout, etc.), and triggers the same events a real user would.
While the agent navigates, every HTTP request and response is captured in real time — including analytics events, tracking pixels, API calls, and third-party scripts. You can inspect this data yourself in the [Network & Console Monitoring](/additional-resources/network-console-monitoring) panel after every run.
You tell Spur what to check using plain language. For example: *"Confirm the product\_detail event contains product\_id, product\_name, and price as a number."* The agent searches the captured network data, finds the matching request, and validates field by field. See [how the agent breaks down and verifies assertions](/additional-resources/network-console-monitoring#understanding-the-result) to understand exactly what happens behind the scenes.
Each validation produces a clear pass or fail, along with the actual data it found — including the endpoint, request method, status code, and payload snippet. You can click through to the [full network log](/additional-resources/network-console-monitoring#viewing-logs-in-test-results) for any examined request. No digging through DevTools required.
***
## Key Concepts
### Events and Payloads
An **event** is a network request your site sends to an analytics platform (like Adobe Analytics, Google Analytics, Tealium, Segment, etc.) when something happens — a page loads, a user clicks a button, an order completes.
Each event carries a **payload**: a bundle of data fields describing what happened. For example, a product view event might include:
```json theme={null}
{
"event_name": "product_detail",
"product_id": "ABC-12345",
"product_name": "Classic Oxford Shirt",
"price": 68.00,
"currency": "USD",
"category": "Men > Shirts",
"brand": "Main Brand",
"color": "Blue",
"size": "M",
"in_stock": true
}
```
When Spur validates an event, it checks:
* **Did the event fire at all?** (The most common failure — roughly 50% of issues)
* **Are all required fields present?** (About 40% of issues)
* **Are the values in the correct format?** (About 10% — wrong types, casing, etc.)
### Log Steps
In Spur, you validate events using **Log steps**. A Log step is a plain-language instruction that tells the agent what to check in the captured network data. You write it like you would explain it to a colleague:
```
Log Confirm the product_detail event fired and contains product_id,
product_name, and price as a number
```
The agent handles the rest — finding the right request, parsing the payload, and checking each field.
See how Spur captures network traffic and console output, how the agent verifies your assertions, and how to inspect raw logs in test results.
Technical reference for writing Log steps, adding them to tests, and troubleshooting.
***
## Thinking Through Your Validation Strategy
Before building tests, take a step back and think about what matters most. Not every event needs the same level of scrutiny.
### Prioritize by Business Impact
```mermaid theme={null}
graph TD
A["All Tracked Events"] --> B{"Revenue impact?"}
B -->|Yes| C["P0 — Validate every deploy"]
B -->|No| D{"Decision-making impact?"}
D -->|Yes| E["P1 — Validate weekly"]
D -->|No| F{"Compliance / legal?"}
F -->|Yes| G["P0 — Validate every deploy"]
F -->|No| H["P2 — Validate monthly"]
style C fill:#fcc,stroke:#c33
style G fill:#fcc,stroke:#c33
style E fill:#fec,stroke:#c93
style H fill:#cfc,stroke:#3c3
```
**P0 — Must validate every deploy:**
* Order confirmation / purchase events (revenue attribution)
* Affiliate and commission tracking (direct revenue impact)
* Consent and privacy events (legal compliance)
* Core conversion events (signup, subscription)
**P1 — Validate weekly or after relevant changes:**
* Product detail page views (merchandising analytics)
* Search and navigation events (UX analytics)
* Campaign attribution parameters (marketing ROI)
**P2 — Validate monthly or on major releases:**
* Page scroll and engagement events
* Feature usage tracking
* A/B test instrumentation
### Map Your Validation Matrix
For each priority event, consider the dimensions you need to cover:
| Dimension | Example |
| ----------------------- | --------------------------- |
| **Regions** | US, UK, EU, APAC |
| **Brands / Properties** | Main brand, sub-brands |
| **Browsers** | Chrome, Safari, mobile |
| **Environments** | Staging, production |
| **User states** | Logged in, guest, returning |
Spur runs all of these combinations in parallel — what takes hours manually takes minutes automated.
***
## Building Your First Validation Test
Here is how to approach it, step by step.
### Step 1: Pick your highest-priority event
Start with the one event that would cause the most damage if it broke. For most teams, this is either:
* **Purchase / order confirmation** — revenue and attribution
* **Main page view event** — highest volume, most dependencies
### Step 2: Document what "correct" looks like
Write down (or gather from your tech spec):
* The event name or endpoint
* Every required field
* The expected data type for each field (string, number, boolean)
* Any format requirements (e.g., currency as decimal, IDs as strings)
### Step 3: Create the test in Spur
Build a test that:
1. Navigates to the page or completes the user flow
2. Uses **[Log steps](/additional-resources/network-console-monitoring)** to validate the event payload
Example test structure:
```
1. Navigate to a product detail page
2. Verify the product page loaded (UI check)
3. Log Confirm the product_detail event fired
4. Log Confirm product_detail contains product_id as a non-empty string
5. Log Confirm product_detail contains price as a number greater than 0
6. Log Confirm product_detail contains product_name, category, and brand
```
### Step 4: Run and iterate
Run the test against your staging environment first. Review the results using the [Network & Console Monitoring](/additional-resources/network-console-monitoring#viewing-logs-in-test-results) panel:
* Did the agent find the right event? Click the examined request badge to verify.
* Are there false positives (flagging things that are actually fine)?
* Are there fields you forgot to include?
Tune your Log step assertions until the test reliably catches real issues and ignores noise. See [best practices for writing effective assertions](/additional-resources/network-console-monitoring#writing-effective-assertions) for tips.
### Step 5: Schedule and expand
Once validated, schedule the test to run:
* **After every deploy** — catch regressions immediately
* **Daily** — catch issues from third-party script updates or infrastructure changes
Then repeat for your next priority event.
***
## Common Validation Patterns
### Analytics Event Validation
The most common use case. Confirm that tracking events fire with the correct payload during key user flows.
```
Log Confirm the purchase event contains order_id, revenue as a number,
and items as an array with at least one entry
```
### Affiliate and UTM Parameter Validation
UTM parameters and affiliate tokens in URLs drive campaign attribution and commission payouts. If they are dropped or malformed at any point in the funnel, revenue goes untracked.
```
Log Confirm the request URL to the affiliate endpoint contains
utm_source, utm_medium, and utm_campaign parameters
```
### Data Layer Validation
Many analytics implementations use a data layer (like Tealium's `utag.data` or Google's `dataLayer`) that is accessible in the browser. Spur can capture and validate these attributes as part of the same test flow.
```
Log Confirm the data layer contains user_segment and page_type
with non-empty values
```
### Cross-Platform Consistency
Run the same validation across Chrome, Safari, and mobile to ensure events fire consistently across all platforms.
***
## What Changes With Automation
| | Manual | Automated with Spur |
| ----------------------------- | ---------------------------------------------- | ----------------------------------------------------- |
| **Time per validation cycle** | 2–4 hours | 5–10 minutes |
| **Coverage** | Spot-checking (\~30%) | 100% — all fields, every run |
| **Multi-region** | Each tested separately | All regions in parallel |
| **Multi-browser** | Manual switching | Chrome, Safari, mobile in parallel |
| **Error detection** | Visual inspection — easy to miss subtle issues | AI flags exact discrepancies with expected vs. actual |
| **Documentation** | Manual screenshots | Structured reports with network traces |
| **Frequency** | Ad-hoc after releases | Scheduled daily + on-demand |
| **Detection speed** | Days to weeks (or never) | Within minutes of a deploy |
***
## Getting Started
Now that you understand the fundamentals of how analytics validation works with Spur, dive into the feature documentation to see exactly how to use it:
See how validation results look in practice — assertion breakdowns, evidence, and raw network/console logs.
Technical reference for adding Log steps to your tests.
Step-by-step guide to building and running your first Spur test.
Execute and monitor your validation tests across environments.
Trigger validation tests automatically on every deploy.
Set up recurring validation runs on a daily or weekly cadence.
# Azure SSO
Source: https://docs.spurtest.com/additional-resources/sso-providers/azure-sso
## Overview
Spur uses Supabase Auth as its authentication provider, which enables secure OAuth 2.0-based SSO. Users can sign in to Spur using their existing identity provider credentials — no separate Spur password required.
## How SSO Works in Spur
Spur's SSO uses the OAuth 2.0 / OpenID Connect (OIDC) protocol — the modern industry standard for federated authentication. Here's the flow when a user signs in:
The user clicks **Sign in with Microsoft** on the Spur login page.
Spur redirects to Microsoft's authentication endpoint.
The user authenticates with their Microsoft credentials (and MFA, if configured by your organization).
Microsoft returns a secure token to Spur confirming the user's identity.
Spur creates or resumes the user's session. No Spur-specific password is ever set or stored.
## What Spur Supports
| Item | Details |
| --------------------- | ------------------------------------------------------------------------------------------------------- |
| **Protocol** | OAuth 2.0 / OpenID Connect (OIDC) |
| **Identity Provider** | Microsoft Azure Entra ID (and Google) |
| **Tenant type** | Multi-tenant — any Azure Entra organization can connect without per-tenant configuration on Spur's side |
| **Account types** | Organizational accounts (work/school). Personal Microsoft accounts are not in scope. |
| **User provisioning** | Just-in-time — a Spur account is automatically created on first successful SSO login |
| **MFA enforcement** | Honored — if your Azure tenant requires MFA, it will be enforced before Spur grants access |
| **Scopes requested** | `openid`, `email`, `profile` (read-only identity data only) |
## Current Limitations
The following are not supported at this time. If any of these are requirements for your organization, please reach out to discuss your use case.
* **SAML 2.0** — Spur uses OAuth 2.0/OIDC only, not SAML.
* **Per-tenant app registration** — Spur uses a single multi-tenant Azure app registration rather than a dedicated registration per customer.
## What Your Organization Needs to Do
For most organizations, no setup is required. Users can sign in with their Microsoft account immediately once Spur enables the provider.
### If Your Tenant Restricts Third-Party App Access
Some organizations configure Azure Entra to require admin approval before users can sign into third-party applications. If this applies to your tenant, an Azure admin will need to:
Navigate to **Azure Portal** → **Microsoft Entra ID** → **Enterprise Applications**.
Locate the Spur application. It will appear after the first sign-in attempt, or can be added proactively.
Grant admin consent for the scopes Spur requests: `openid`, `email`, and `profile`.
This is a one-time action that unblocks all users in your organization without each person needing to consent individually.
### Restricting Access to Specific Users or Groups
If you want to limit which employees in your organization can access Spur via SSO, an Azure admin can:
1. In the Spur enterprise application in Entra, enable **User assignment required**.
2. Assign specific users or Azure groups who are permitted to sign in.
Without this configuration, any user in your organization's Azure tenant can sign into Spur.
## Data & Security
Spur requests the minimum necessary permissions to authenticate your users. Spur does not request access to email content, calendar, files, or any other Microsoft 365 data.
* **openid** — Required to use OpenID Connect for authentication
* **email** — The user's email address, used as their Spur account identifier
* **profile** — Basic profile info (name), used to populate the user's Spur profile
## Questions?
If you have questions about SSO configuration, compliance requirements, or want to discuss your organization's specific setup, please contact your Spur account representative.
Reach out to the Spur team for SSO support.
# Google SSO
Source: https://docs.spurtest.com/additional-resources/sso-providers/google-sso
## Overview
Spur uses Supabase Auth as its authentication provider, which enables secure OAuth 2.0-based SSO. Users can sign in to Spur using their existing Google Workspace credentials — no separate Spur password required.
## How SSO Works in Spur
Spur's SSO uses the OAuth 2.0 / OpenID Connect (OIDC) protocol — the modern industry standard for federated authentication. Here's the flow when a user signs in:
The user clicks **Sign in with Google** on the Spur login page.
Spur redirects to Google's authentication endpoint.
The user authenticates with their Google credentials (and MFA, if configured by your organization).
Google returns a secure token to Spur confirming the user's identity.
Spur creates or resumes the user's session. No Spur-specific password is ever set or stored.
## What Spur Supports
| Item | Details |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Protocol** | OAuth 2.0 / OpenID Connect (OIDC) |
| **Identity Provider** | Google Workspace |
| **Account types** | Google Workspace accounts (organizational). Personal Gmail accounts are not supported — this is enforced by configuring the OAuth app's user type to **Internal** in the Google Cloud Console. |
| **User provisioning** | Just-in-time — a Spur account is automatically created on first successful SSO login |
| **MFA enforcement** | Honored — if your Google Workspace requires MFA, it will be enforced before Spur grants access |
| **Scopes requested** | `openid`, `email`, `profile` (read-only identity data only) |
## Current Limitations
The following are not supported at this time. If any of these are requirements for your organization, please reach out to discuss your use case.
* **SAML 2.0** — Spur uses OAuth 2.0/OIDC only, not SAML.
## What Your Organization Needs to Do
For most organizations, no setup is required. Users can sign in with their Google Workspace account immediately.
### If Your Organization Restricts Third-Party App Access
Some organizations configure Google Workspace to restrict which third-party apps users can sign into. If this applies to your organization, a Google Workspace admin will need to:
Navigate to the [Google Admin Console](https://admin.google.com) → **Security** → **Access and data control** → **API controls**.
Click **Manage Third-Party App Access** and find or add the Spur application.
Set the app to **Limited** so that users in your organization can sign in without individual approval. This allows the app to request access to unrestricted Google data only, which is sufficient for SSO.
This is a one-time action that unblocks all users in your organization without each person needing to consent individually.
### Restricting Access to Specific Users or Groups
If you want to limit which employees in your organization can access Spur via SSO, a Google Workspace admin can:
1. In the Google Admin Console, navigate to the Spur app under **API controls**.
2. Restrict the app to specific organizational units (OUs) or groups.
Without this configuration, any user in your Google Workspace organization can sign into Spur.
## Data & Security
Spur requests the minimum necessary permissions to authenticate your users. Spur does not request access to Gmail, Google Drive, Calendar, or any other Google Workspace data.
* **openid** — Required to use OpenID Connect for authentication
* **email** — The user's email address, used as their Spur account identifier
* **profile** — Basic profile info (name), used to populate the user's Spur profile
## Questions?
If you have questions about SSO configuration, compliance requirements, or want to discuss your organization's specific setup, please contact your Spur account representative.
Reach out to the Spur team for SSO support.
# User Roles
Source: https://docs.spurtest.com/additional-resources/user-roles
Understand the difference between admin and member roles, and how admins manage your team in Spur.
## Overview
Spur has two user roles:
| Role | Permissions |
| ---------- | ---------------------------------------------------------------------------------------------------------- |
| **Admin** | Everything a member can do, plus: invite new users, promote members to admin, and demote admins to member. |
| **Member** | Author, run, and analyze tests. Cannot manage team membership or roles. |
Every account needs at least one admin. Removing users from an account is not yet supported — if you need a user removed, [contact the Spur team](/additional-resources/contact-us).
If your team does not yet have an admin or you need someone promoted, email [andy@tryspur.dev](mailto:andy@tryspur.dev).
## Managing Your Team
All team management happens on the [Account page](https://app.spurtest.com/account). Only admins can see the team management controls.
### Invite a New User
Go to [app.spurtest.com/account](https://app.spurtest.com/account).
Enter the new user's email address and submit.
Spur creates an account for the user and emails them a link to set their password. Once they set a password, they can sign in.
New users are added as **members** by default. Promote them to admin afterward if they need team management permissions.
### Promote a Member to Admin
On the [Account page](https://app.spurtest.com/account), find the member in the team list and change their role to **Admin**. The change takes effect immediately.
### Demote an Admin to Member
On the [Account page](https://app.spurtest.com/account), find the admin in the team list and change their role to **Member**. Make sure at least one admin remains on the account.
## Related
Set up Google or Azure SSO so users can sign in with their organization's credentials.
Need a user removed or have a role question we haven't covered? Reach out.
# Analysis Overview
Source: https://docs.spurtest.com/analysing-tests/analysis-overview
Understand where to find your test results and what you can do with them.
## Overview
Once your tests have run, Spur gives you several ways to view, analyze, and act on the results. Whether you need a quick health check across all your suites or a deep dive into a specific test plan run, everything is accessible from the Spur dashboard.
## Where to Find Your Results
The best way to work through your results. The Test Plan Review flow walks you through every failure and warning in a test plan run, letting you triage each result, edit tests inline, and create bug tickets without leaving Spur. Start here if you run tests through test plans.
A bird's-eye view of the latest result for every test across all your suites. Use this to quickly spot which tests are failing, passing, or raising warnings. Results are split by viewport, environment, and browser.
## What You Can Do with Results
Once you have your results, Spur provides several ways to take action:
### Share Results
Share test results with your team without requiring a Spur login. Shareable links give the recipient full access to the test result, including steps, video replay, console logs, and network logs.
Generate a link to any test result and send it to anyone on your team.
### Create Bug Tickets
Turn failures into trackable issues in your project management tool. Spur auto-populates tickets with failure details, screenshots, and reproduction steps.
Create Jira tickets directly from test failures.
Create Linear issues directly from test failures.
### Get Notified
Set up alerts so your team is informed about test results automatically, whether through Slack messages or email notifications.
Receive test result notifications in your Slack channels.
Get email notifications for test outcomes.
### Debug with Spur MCP
Pass shareable links to the Spur MCP to analyze test results and help debug failures directly in your development workflow.
Use AI-powered analysis to understand and fix test failures.
# Email Alerts
Source: https://docs.spurtest.com/analysing-tests/integrations/email
Configure email notifications for test results and alerts.
## Overview
The email integration keeps your team informed about test results without needing to check the Spur dashboard. You can configure notifications for specific test outcomes and control who receives alerts from which suites.
## Setup
Navigate to the [Integrations page](https://app.spurtest.com/integrations) and select **Email** from the available integrations.
Choose which notifications you want to receive:
Immediate alerts when any test fails.
Confirmation when tests pass.
A daily digest of all test results.
Control who gets alerts from which suites.
## Per-User Access Settings
By default, every user in your application receives email notifications for all tests. You can configure specific access settings to control who gets alerts from which suites.
If you configure access for one person, make sure to configure access for everyone else as well. Otherwise, unconfigured users will continue to receive notifications for all suites.
Go to the Integrations tab and click into **Access Settings** for the email integration.
For each user, select which suites they should receive notifications for. This gives you fine-grained control over who sees what.
# GitHub Integration
Source: https://docs.spurtest.com/analysing-tests/integrations/github
Connect Spur with GitHub for automated testing on pull requests.
## Overview
The GitHub integration lets you run Spur tests automatically on every pull request. Test results appear as status checks directly on the PR, and you can use branch protection rules to block merges when tests fail.
Test plans run automatically on every pull request without manual intervention.
Pass/fail results appear directly on the pull request in GitHub.
For a full setup walkthrough including YAML workflow files and branch protection, see the [GitHub CI/CD guide](/running-tests/cicd/github).
## Quick reference
Spur automatically generates the workflow YAML files for your repository. You can download them from the GitHub Integration Settings page in Spur and add them to your repository under `.github/workflows/`.
The full CI/CD setup guide covers everything you need, including configuring test plans, downloading YAML files, and enabling branch protection. See the [GitHub CI/CD page](/running-tests/cicd/github) for step-by-step instructions.
# GitLab Integration
Source: https://docs.spurtest.com/analysing-tests/integrations/gitlab
Connect Spur with GitLab for automated testing on merge requests.
## Overview
The GitLab integration lets you run Spur tests automatically on every merge request. Test results appear as pipeline status checks directly on the MR, helping your team catch issues before merging.
Test plans run automatically on every merge request without manual intervention.
Pass/fail results appear directly on the merge request in GitLab.
For a full setup walkthrough including `.gitlab-ci.yml` configuration, see the [GitLab CI/CD guide](/running-tests/cicd/gitlab).
## Quick reference
Add the Spur test stage to your `.gitlab-ci.yml` file to trigger test plans on merge request events. Spur provides the configuration you need from the GitLab Integration Settings page.
The full CI/CD setup guide covers everything you need, including configuring test plans and pipeline setup. See the [GitLab CI/CD page](/running-tests/cicd/gitlab) for step-by-step instructions.
# Integrations Overview
Source: https://docs.spurtest.com/analysing-tests/integrations/integrations
Setup instructions of integrations, and a list of all currently available integrations.
# Setting up your Integrations
1. Click the User Profile button in the top right, from any page.
2. Click Integrations in the dropdown.
3. Connect and manage your integrations!
# Available Integrations
## Issue Tracking & Bug Reporting
Jira and Linear follow the same workflow in Spur. Both let you create bug tickets from test failures with auto-populated details. The setup and ticket creation steps are identical across both integrations.
Create detailed Jira tickets directly from test failures with screenshots, logs, and reproduction steps.
Create Linear issues directly from test failures with auto-populated details and reproduction steps.
## Communication & Notifications
Real-time notifications and alerts in your Slack workspace
Customizable email notifications and reports
## Development Workflows
GitHub and GitLab follow the same workflow in Spur. Both let you trigger test plans automatically on pull requests or merge requests, with results appearing as status checks.
Automated testing workflows and Vercel preview deployment
Run Spur tests in your GitLab CI/CD pipelines with automated test execution on merge requests.
# Jira Tickets
Source: https://docs.spurtest.com/analysing-tests/integrations/jira
Connect Spur with Jira to file bug tickets from failed test runs, sync ticket status back to Spur, and set project, priority, and assignee defaults.
## Setup
If you have not integrated Spur with Jira, follow the setup process [here](/analysing-tests/integrations/integrations).
## Overview
Connecting to our Jira integration allows you to create bug tickets directly from test failures. You can choose which project to send tickets to, along with details such as priority and assignee.
## Permissions
When you authorize the integration, Spur requests the following Jira OAuth scopes. Each one maps directly to a feature of the integration:
| Scope | Why Spur needs it |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `read:jira-work` | Lists your projects, issue types, and issue fields so the ticket creation modal is pre-populated with your project's setup. Also used to fetch issue details for tickets linked to Spur tests. |
| `write:jira-work` | Creates bug tickets from test failures and attaches supporting evidence, such as test videos and screenshots, to the ticket. |
| `read:jira-user` | Fetches the names and avatars of assignable users so you can pick an assignee when creating a ticket. |
| `manage:jira-configuration` | Reads your Jira configuration — available priorities, statuses, and fields — so the ticket creation form matches your instance. Atlassian gates read access to these configuration objects behind this scope; Spur never creates or modifies projects, workflows, or custom fields. |
| `offline_access` | Keeps the integration connected by refreshing access tokens, so you don't have to re-authorize Spur. |
Spur only acts on your Jira workspace when you create a ticket from a test failure. It never modifies your Jira configuration or deletes data on its own.
## Creating a ticket manually from a test failure
After reviewing a test run, open the Share menu and click the "Create a Ticket" button to open the Jira ticket creation modal:
The modal opens with pre-populated information from the test failure:
**Auto-Generated Fields:**
* **Title**: Name of the Test
* **Description**: Detailed bug report including:
* Failure Reason
* Reproduction steps
* Test name and execution details
* **Project**: The default project, if chosen in the Integrations page.
Edit the title and description, if necessary. Choose additional ticket details.
**Customization Options:**
* **Assignee**: Set who should handle the ticket
* **Priority**: What is the urgency of this bug?
* **Due Date**: When will this ticket be considered overdue?
Create the ticket!
## Viewing and syncing linked tickets
Once a Jira ticket is linked to a test, Spur displays it in the test's share panel with live status information pulled directly from Jira.
### Status pill
Each linked ticket shows a **status pill** reflecting its current Jira workflow state—for example, **Open**, **In Progress**, or **Done**. The status is displayed alongside the ticket key so you can see the current state at a glance without leaving Spur.
### Syncing ticket data
Click the **Sync** button next to a linked ticket to pull the latest information from Jira. Syncing updates:
* **Title** — Current ticket summary
* **Status** — Current workflow state
* **Assignee** — Current ticket owner
* **URL** — Link to the Jira issue
This is useful when a ticket has been updated in Jira since it was first linked—for example, if it has been reassigned, triaged, or resolved.
## Troubleshooting
### Common issues
**If fields are missing:**
* Your integration permissions may not be set properly. Try reintegrating from the Integrations page.
**Ticket Creation Failures:**
* Confirm you have chosen a proper project and issue type
* Check required field configurations
**Custom Required Fields:**
* If your Jira project has custom required fields, [contact the Spur team](/additional-resources/contact-us) for assistance with your integration setup.
# Linear Tickets
Source: https://docs.spurtest.com/analysing-tests/integrations/linear
Connect Spur with Linear for streamlined issue tracking and automated bug reporting.
## Setup
If you have not integrated Spur with Linear, follow the setup process [here](/analysing-tests/integrations/integrations).
## Overview
Connecting to our Linear integration allows you to create bug tickets directly from test failures. You can choose which team and project to send issues to, along with details such as priority, assignee, and labels.
## Creating a Ticket Manually from a Test Failure
After reviewing a test run, open the Share menu and click the "Create a Ticket" button to open the Linear issue creation modal:
The modal opens with pre-populated information from the test failure:
**Auto-Generated Fields:**
* **Title**: Name of the Test
* **Description**: Detailed bug report including:
* Failure Reason
* Reproduction steps
* Test name and execution details
* **Team**: The default team, if chosen in the Integrations page.
Edit the title and description, if necessary. Choose additional issue details.
**Customization Options:**
* **Project**: Which project should this ticket be in? This is optional.
* **Assignee**: Set who should handle the issue
* **Priority**: What is the urgency of this bug?
* **Labels**: Attach any labels that are allowed within the selected team.
* **State**: Choose the current status of the issue
Create the issue!
## Troubleshooting
### Common Issues
**If fields are missing:**
* Your integration permissions may not be set properly. Try reintegrating from the Integrations page.
**Issue Creation Failures:**
* Confirm you have chosen a proper team
* Check required field configurations
**Custom Required Fields:**
* If your Linear workspace has custom required fields, [contact the Spur team](/additional-resources/contact-us) for assistance with your integration setup.
# Slack Alerts
Source: https://docs.spurtest.com/analysing-tests/integrations/slack
Connect Spur with Slack for real-time test result notifications in your workspace.
## Overview
The Slack integration sends test result notifications directly to a channel in your workspace. You can receive alerts when tests fail, when they pass, or get a daily summary of all results.
## Setup
In your Slack workspace, create a new channel for Spur notifications (e.g. `#spur_alerts`).
Navigate to the Integrations page and click **Connect** on the Slack card. Authorize Spur to access your workspace when prompted.
Go to the Integrations page in Spur to connect your Slack workspace.
## Permissions
When you authorize the integration, Spur requests the following Slack OAuth scopes. Each one maps directly to a feature of the integration:
| Scope | Why Spur needs it |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `chat:write` | Sends test result alerts and end-of-day summaries to your chosen channel as Spur. |
| `channels:read` | Lists the public channels in your workspace so you can pick a notification channel when configuring alerts or test plans. |
| `groups:read` | Lists private channels that Spur has been added to, so they also appear in the channel picker. |
| `channels:join` | Lets Spur join a public channel automatically when it needs to deliver an alert there, so you don't have to invite the bot manually. |
| `incoming-webhook` | Lets you post Spur alerts to a specific channel via a webhook URL as an alternative to selecting a channel. |
| `links:read` | Detects when `app.spurtest.com` test result links are shared in your channels. |
| `links:write` | Shows rich previews of shared `app.spurtest.com` links, including the test name, status, and failure reason. |
| `links.embed:write` | Embeds the test recording video player directly in those link previews. |
| `app_mentions:read` | Lets Spur see messages that directly @-mention the Spur app in channels it has been added to. |
Spur can only see channel names for the channel picker and messages that contain `app.spurtest.com` links or @-mention Spur. It cannot read your other messages.
## Notification Options
Once connected, you can choose when Spur sends alerts to your channel:
* **On Fail** — Get notified when one or more tests fail.
* **On Pass** — Get notified when tests pass.
* **End of Day Summary** — A daily digest of all test results.
You can also customize the Slack channel and notification trigger per test plan. Test plans can send alerts to their own dedicated channels. See the [Running Test Plans](/running-tests/test-plans) page for details.
# Spur MCP Integration
Source: https://docs.spurtest.com/analysing-tests/mcp/spur-mcp
Give your AI assistant access to Spur through the Model Context Protocol to run tests, analyze results, and debug failures without leaving your editor.
MCP (Model Context Protocol) is a way to give your AI assistants and agents access to external tools and data — so they can take actions on your behalf, not just answer questions. With Spur's MCP server, your AI assistant can run tests, analyze results, and help you debug failures — all without leaving your editor.
## Common Workflows
*"Run any tests I have for checkout"*
The agent finds matching tests and lets you run them directly from the conversation.
[See this in action](/analysing-tests/mcp/spur-mcp-discover-tests)
*"What went wrong in this run?"*
The agent reviews step results, console logs, and screenshots to surface the root cause.
*"What is missing from my checkout flow test coverage?"*
Your agent is provided with information about all your tests across suites and environments to identify gaps.
*"Help me fix the bug from this failed test"*
The agent pulls failure details, logs, and context to help you resolve issues in your code.
[See this in action](/analysing-tests/mcp/spur-mcp-fix-bugs)
*"Generate and save tests for this PR"*
The agent analyzes your code, generates test steps, and creates them directly in Spur via `create_test` — no manual copy-paste required.
[See this in action](/analysing-tests/mcp/spur-mcp-in-sprint-testing)
*"Run the regression suite and tell me what failed"*
The agent triggers a full test plan run, then walks through every failure with detailed context for each one.
[See this in action](/analysing-tests/mcp/spur-mcp-test-plans)
*"Run the Spur test that covers this Jira ticket and this GitHub PR"*
Connect other tools, providing additional context to optimize your testing. Let your AI agent decide what to test.
[See this in action](/analysing-tests/mcp/spur-mcp-connecting-other-mcps)
*"Here's PR #247 — generate test cases for the search modal changes"*
Use Claude Code with your codebase context to generate, run, and iterate on tests directly from PRs and tickets — all within your sprint cycle.
## Available Tools
`list_tests` – Lists all tests in the active application with IDs, suites, URLs, and scenario table status. Accepts optional filters: `test_id` for full step-level detail (replaces the old `get_test_details`), `suite_id` to scope to a single suite, and `query` for a name search
`list_suites` – Lists all suites with their allowed environments, URL keys, and connected scenario table. Pass `suite_id` to also return every test in that suite
`list_folders` – Lists all folders in the active application. Without a `folder_id`, returns a summary of every folder; with a `folder_id`, returns that folder's details and the suites it contains
`list_scenarios` – Lists all scenario tables with columns and row names. Pass `table_name` to see the full cell values for every row — use this when you need actual data to build test steps or configure a test plan
`list_environments` – Lists all environments with type, validity status, and how many suites can use each one. Pass `env_name` to see every property and its configured value (URLs, headers, secrets, build references)
`list_login_tests` – Lists login tests compatible with a suite and test type: tests that save login state, cover every environment the suite runs on, and match the platform (web or native). Pass a returned id to `create_test` or `update_test` as `from_login_test_id`
`list_test_plans` – Lists all test plans with suite counts, environments, and last run time. Pass `plan_id` to get the full editable configuration — required before calling `update_test_plan`
`get_test_guidance` – Returns Spur's test-writing best practices and the full step format reference (browser actions, verifies, extracts, JavaScript injection, network log assertions, email, variables). Call this before `create_test` or `update_test` so generated steps use the correct syntax
`create_test` – Creates and saves a new test to a suite. Requires a `suite_id`, `title`, `env_key_name`, and `steps`. Use `list_suites` first to discover valid values. The agent will show you a full summary and ask for approval before saving
`update_test` – Updates an existing test by `test_id`. Accepts any combination of `title`, `env_key_name`, and `steps`. Replaces all steps when `steps` is provided. The agent will show you what will change and ask for approval before saving
`generate_test_steps_from_loom` – Turns a public Loom video into a DRAFT list of test steps (server-side analysis of screen and narration). Does not save anything on its own — normalize the draft with `get_test_guidance`, confirm suite and environment, then call `create_test`
`save_suite` – Creates a new test suite or updates an existing one. Can also move tests into the suite, place the suite in a folder, or replace the suite's full dependency graph (test ordering and variable flow). Validates every change up front and rejects moves that would break environments, dependencies, or scenario tables
`create_scenario_table` – Creates a scenario table with optional columns and rows. Use `list_scenarios` first to check what already exists
`update_scenario_table` – Edits a scenario table's columns or rows. Use `list_scenarios` first to see the current state
`add_scenario_rows` – Adds new rows to an existing scenario table. Provide the `table_name` (from `list_scenarios`) and an array of rows, each with a unique `name` and a `values` map of column name → value
`connect_scenario_table` – Connects or disconnects a scenario table from a suite. A suite can only have one scenario table at a time. Use `action: "connect"` or `"disconnect"` along with the `table_name` and `suite_id`
`run_tests` – Runs one or more tests in a single collection run, grouped by shared configuration. Specify `env_name` (environment name) along with optional `viewport`, `browser`, and `scenario_row_name`
`run_test_plan` – Triggers a full test plan run across all configured suites and environments
`get_test_run_overview` – **Start here.** Summarizes a run's status, step results, warnings, and failures
`get_test_run_details` – Deep dive into steps, sub-steps, configs, and artifacts. Use after the overview
`get_test_runs` – Lists the last 50 runs for a given test
`get_recent_runs` – Returns the most recent runs across the application or filtered by suite or test within a time window. Results are grouped by collection run and include status, metadata (scenario, browser, viewport, environment, test type), duration, and `task_id` for drilling into individual runs
`get_coverage_snapshot` – Whole-window coverage aggregates computed server-side over every run in the window: runs and failures per environment, distinct tests run per suite × environment, suites with zero runs, browser and viewport totals, and every failed run. Use this for coverage reports instead of paging `get_recent_runs`
`get_test_run_console_logs` – Browser console output and JavaScript errors. Supports `contains` for case-insensitive substring search and `limit`/`offset` for paging
`get_test_run_network_logs` – HTTP requests and responses captured during the run. Supports `contains` (URL fragment, status code, or method) and `limit`/`offset` for paging
`get_test_run_screenshots` – Screenshots from the test execution for visual inspection
`list_test_plans` – Lists all test plans with their names, suites, environments, and last run time. Pass `plan_id` to get the full editable configuration needed for `update_test_plan`
`create_test_plan` – Creates a new test plan grouping suites and environments for coordinated execution. The agent will show you the full plan summary and ask for approval before saving
`update_test_plan` – Updates an existing test plan. Always call `list_test_plans` with `plan_id` first to get the current configuration — the new suites list replaces the existing one entirely
`get_test_plan_runs` – Returns recent run history for a test plan: timestamps, pass/fail counts, and run IDs
`get_test_plan_run_overview` – **Key triage tool.** Shows every test result in a plan run — failures first with failure reasons. Use `task_id` values from here to drill into individual failures with the run analysis tools
`applications` – Lists all applications on your account, or switches the active one. Omit `application_name` to list; provide it to switch. All subsequent tool calls will use the newly selected application
## How to Set Up
Get started with Cursor, Claude Code, GitHub Copilot in VS Code, or ChatGPT.
Authentication uses OAuth. When you connect for the first time, your browser will open to authorize access to your Spur account.
## Best Practices
* **Allow all tool calls except test execution and authoring**: Set your MCP client to auto-approve read-only Spur tool calls. Keep `run_tests`, `run_test_plan`, `create_test`, `update_test`, `create_test_plan`, `update_test_plan`, `save_suite`, `create_scenario_table`, `update_scenario_table`, `add_scenario_rows`, and `connect_scenario_table` on manual approval — these tools write or trigger things on your behalf, so you should review what will happen before they proceed.
* **Model quality matters**: More capable models produce better results when choosing the right tools and interpreting test output. Smaller models may need more explicit guidance.
# Connecting with Other MCP Tools
Source: https://docs.spurtest.com/analysing-tests/mcp/spur-mcp-connecting-other-mcps
Combine the Spur MCP with GitHub, Jira, Linear, and other tools to give your AI assistant richer context for testing.
The Spur MCP becomes more powerful when your AI assistant has access to other tools alongside it. By connecting MCPs for project management, source control, or communication, your agent can pull in context from across your workflow — and make smarter decisions about what to test, when to test it, and how to interpret results.
## GitHub
Connect a GitHub MCP so your agent can read pull requests, commits, and code changes — then match them to the right Spur tests.
### Example prompts
* *"Run any Spur tests that cover the files changed in this PR"*
* *"This commit broke checkout — find the relevant Spur test and show me what failed"*
* *"What Spur test coverage do I have for the code in PR #142?"*
### How it works
Your agent uses the GitHub MCP to fetch the changed files, commit messages, or PR description.
Using the context from GitHub, the agent calls `list_tests` and `get_test_details` to find Spur tests that cover the affected areas.
The agent runs the matching tests with `run_test`, then summarizes results — so you know whether your changes are safe before merging.
## Jira
Connect a Jira MCP so your agent can read tickets, acceptance criteria, and bug reports — then tie them directly to Spur test runs.
### Example prompts
* *"Run the Spur test that covers Jira ticket SHOP-451"*
* *"This Jira bug says checkout is broken — find and run the relevant Spur tests"*
* *"Check if I have Spur test coverage for the acceptance criteria in SHOP-302"*
### How it works
Your agent uses the Jira MCP to fetch the ticket summary, description, and acceptance criteria.
The agent calls `list_tests` and `get_test_details` to find Spur tests that match the ticket scope, then presents them for you to run.
The agent runs the matching tests with `run_test`, then summarizes the results — so you know which acceptance criteria are passing and which need attention.
## Linear
Connect a Linear MCP so your agent can read issues, project context, and cycle priorities — then link them to your Spur test suite.
### Example prompts
* *"Run Spur tests related to the issues in the current sprint"*
* *"This Linear issue says the login flow is broken — find and run the matching Spur test"*
* *"What Spur test coverage do I have for the issues assigned to me?"*
### How it works
Your agent uses the Linear MCP to fetch issue details, labels, and project context.
The agent calls `list_tests` and `get_test_details` to find Spur tests that align with the issue scope.
The agent executes the relevant tests and reports back with results mapped to the Linear issue, so you can update the issue status with confidence.
## Other tools
Any MCP that gives your agent context about *what changed* or *what matters* pairs well with Spur. The pattern is always the same: the external tool provides context, and Spur provides the testing.
Examples of other MCPs that work well alongside Spur:
* **Slack** — *"Someone reported a bug in #engineering — find and run the relevant Spur test"*
* **Notion** — *"Run Spur tests for the features listed in this Notion spec"*
* **GitLab** — *"Run tests covering the files in this merge request"*
# Discover and Run Tests
Source: https://docs.spurtest.com/analysing-tests/mcp/spur-mcp-discover-tests
Use your AI assistant to explore what tests are available in Spur and run them without leaving your editor.
## Who is this for?
If you've just joined a team using Spur — or you are taking a look at tests someone else wrote — you may not know what test coverage already exists. Rather than clicking through the Spur dashboard to find out, you can ask your AI assistant to tell you.
This workflow is especially useful when you:
* Are new to a codebase and want to understand what's already tested
* Need to run tests for a feature you're working on but aren't sure what's available
* Want to quickly check if a specific flow has coverage before writing new tests
## Walkthrough
Start with a broad question like *"What tests do I have?"* or narrow it down: *"What tests do I have for Adding to Cart?"*
Your agent calls `list_tests` to pull all tests in your active application, then filters by name and description to find relevant matches.
The agent returns a list of matching tests with their IDs, suites, URLs, and descriptions. You can ask follow-up questions like *"What does the checkout test cover?"* to get full step details via `list_tests` with the `test_id`.
Once you've found the right test, tell your agent to run it: *"Run this on staging."*
The agent calls `run_tests` with the correct environment name and configuration, then monitors the run status. The agent will prompt you to fill in any configurations that it is missing.
When the run completes, ask *"How did it go?"* The agent calls `get_test_run_overview` to summarize the results — passing steps, failures, and warnings — so you can decide what to do next.
# Fix Raised Bugs
Source: https://docs.spurtest.com/analysing-tests/mcp/spur-mcp-fix-bugs
Use your AI assistant to pull failure details from Spur and resolve bugs directly in your code.
When a Spur test fails, your AI assistant can pull the failure details — step results, console logs, network requests, and screenshots — and help you trace the issue back to your code.
Instead of switching between the Spur dashboard and your editor, you stay in one place. The agent gathers the context; you fix the bug.
## How It Works
Tell your agent about the failure: *"Help me fix the bug from this failed test"* or paste a run ID directly. You can give the Shareable link, or the direct link to the test run.
The agent calls `get_test_run_overview` to identify which steps failed and why.
The agent automatically pulls deeper context using `get_test_run_details`, `get_test_run_console_logs`, and `get_test_run_network_logs` to surface JavaScript errors, failed HTTP requests, or unexpected behavior.
If the agent deems it necessary, or you provide that instruction, it retrieves screenshots from the run via `get_test_run_screenshots` so it can see exactly what happened in the browser.
With the full context available, your agent can help you identify the root cause and suggest or apply a fix directly in your codebase.
# In-Sprint Test Generation
Source: https://docs.spurtest.com/analysing-tests/mcp/spur-mcp-in-sprint-testing
Use Claude Code and the Spur MCP to generate, run, and iterate on tests directly from pull requests and tickets — without leaving your editor.
When you are working inside a sprint, test coverage often lags behind development. Features ship, PRs merge, and tests get written later — if at all. With Claude Code and the Spur MCP, you can generate and validate tests as part of your development workflow, closing the gap between code changes and test coverage.
This guide walks you through a real-world workflow for generating tests from code context, creating them in Spur via MCP, and iterating on failures — all from within your editor.
## Who is this for?
* QA engineers who want to scale test creation without sacrificing quality
* Developers who want to validate their changes before merging
* Teams looking to shift testing left into the sprint cycle
## Prerequisites
* [Spur MCP set up](/analysing-tests/mcp/spur-mcp-setup) in Claude Code
* A GitHub or Jira MCP connected (for PR/ticket context)
* Claude Code with access to your project codebase
## The Workflow
```mermaid theme={null}
graph LR
A[PR or Ticket] --> B[Claude analyzes code context]
B --> C[Generate test steps]
C --> D[Create test in Spur]
D --> E[Run test]
E --> F{Pass?}
F -->|Yes| G[Done]
F -->|No| H[Analyze failure]
H --> C
```
## Step-by-Step
Start by pointing Claude Code at the change you want to test. This can be a pull request, a Jira ticket, or even a commit hash.
```
"Here's PR #247 — it updates the search modal to clear the
search term on close. Can you generate test cases for this?"
```
Claude reads the PR description, code diffs, and changed files to understand what was modified. Even PRs with minimal descriptions work well — the code diff itself provides rich context about what changed and what needs testing.
With access to your full codebase, Claude goes beyond the PR diff. It examines the surrounding code, related components, and existing test coverage to identify what should be tested.
For example, Claude might identify:
* The primary flow (search term clears on modal close)
* Edge cases (what if the search had active results?)
* Related areas (does the search state persist across navigation?)
You can also ask Claude to prioritize broadly:
```
"What are the highest-priority areas of our app that need
test coverage? Focus on cart, checkout, and navigation."
```
Claude analyzes your codebase structure, identifies critical user flows, and ranks them by importance — giving you a prioritized list of test cases to create.
Claude outputs structured test steps that map directly to what Spur expects. Each test case includes a clear description, preconditions, and step-by-step actions with expected outcomes.
Example output:
```
Test: Search term clears on modal close
1. Navigate to the homepage
2. Click the search icon to open the search modal
3. Type "jacket" in the search field
4. Verify search results appear
5. Close the search modal
6. Reopen the search modal
7. Verify the search field is empty
```
Once you are happy with the test steps, ask Claude to create the test directly in Spur. Claude will:
1. Call `list_suites` to discover available suites and their URL keys
2. Show you a full test summary — suite name, title, URL key and resolved URL, and all numbered steps
3. Ask for your explicit approval before saving
4. Call `create_test` to save the test to the suite
```
"Create this test in the Checkout suite using the staging URL key"
```
After creation, Claude returns the new `test_id` which it can use immediately to run the test.
If you want to revise the test after reviewing the result, ask Claude to update it:
```
"Update that test — change step 3 to click the 'Add to cart' button instead"
```
Claude calls `update_test` with the revised steps, again showing you what will change before saving.
Use the Spur MCP to trigger the test directly from your editor:
```
"Run the search modal test on staging"
```
Claude calls `run_tests` with the correct environment name and monitors the run. You stay in your editor the entire time.
When a test fails, Claude pulls the full debugging context automatically:
* **`get_test_run_overview`** — What failed and at which step
* **`get_test_run_console_logs`** — JavaScript errors or warnings
* **`get_test_run_network_logs`** — Failed API calls or unexpected responses
* **`get_test_run_screenshots`** — Visual state of the browser at failure
Claude then correlates the failure with your codebase to determine whether it is a test issue (wrong selector, timing, incorrect step) or an actual bug in the code.
If the test steps need adjustment, Claude calls `update_test` to revise them in-place and you run again — no need to go back to the Spur UI. If it is a real bug, Claude helps you fix it in your code.
## Scaling with Code-to-Test Mapping
As your test suite grows, you can maintain a mapping between code areas and their corresponding Spur tests. This lets you (or your CI pipeline) automatically identify which tests to run when specific code changes.
### How it works
1. **Map code areas to tests** — Maintain a reference (in your repo or in Spur) that links code paths to test IDs
2. **When a PR touches a file** — Claude checks the mapping and identifies which Spur tests cover the affected area
3. **Run only relevant tests** — Instead of running the full suite, you run targeted tests that correspond to the change
```
"I changed the cart component. What Spur tests should I run?"
```
Claude cross-references the changed files with your test mapping and calls `list_tests` to confirm coverage, then runs the relevant subset with `run_tests`.
### Example mapping
```yaml theme={null}
# test-mapping.yaml
homepage:
paths: ["src/components/Home/**", "src/pages/index.*"]
spur_tests: ["test_id_1", "test_id_2"]
cart:
paths: ["src/components/Cart/**", "src/context/CartContext.*"]
spur_tests: ["test_id_3", "test_id_4", "test_id_5"]
search:
paths: ["src/components/Search/**"]
spur_tests: ["test_id_6", "test_id_7"]
```
## Pairing with Other MCPs
This workflow becomes even more powerful when you combine multiple MCPs:
| MCP | What it adds |
| ----------------- | ------------------------------------------------------ |
| **GitHub** | PR diffs, commit history, changed files |
| **Jira / Linear** | Ticket context, acceptance criteria, sprint priorities |
See [Connecting with Other MCP Tools](/analysing-tests/mcp/spur-mcp-connecting-other-mcps) for setup details.
## CI/CD integration
To fully close the loop, you can trigger Spur tests from your CI pipeline on deploy previews:
1. **Your CI builds a deploy preview** for the PR
2. **A GitHub Action triggers Spur tests** against the preview URL
3. **Spur runs the relevant tests** using [Override URLs](/running-tests/cicd/override-urls) to target the preview environment
4. **Results feed back** to the PR as a status check
This means every PR gets tested automatically against a live preview — catching regressions before they reach staging or production.
Set up GitHub or GitLab pipelines to trigger tests automatically.
Redirect tests to deploy previews or feature branch URLs at runtime.
## Tips from Real Usage
Ask Claude to survey your codebase for high-priority test areas first. Then work through them systematically — one area at a time (cart, then navigation, then checkout). This is more productive than trying to test everything at once.
When authoring tests, use relative paths instead of hardcoded domains. This makes it easy to run the same tests across staging, production, and deploy previews by overriding the base URL in your environment configuration.
As you iterate with Claude Code, it learns your patterns — what step types to use, how to structure verifications, and what edge cases matter for your app. The more you use it, the less iteration you need.
Each test should validate one flow. Avoid combining multiple scenarios into a single test — it makes failures harder to diagnose and steps harder to maintain.
The most efficient workflow is: generate, create, run, analyze failure, fix steps, run again. Claude can drive this entire loop, only pausing for your approval before running tests.
# MCP Setup
Source: https://docs.spurtest.com/analysing-tests/mcp/spur-mcp-setup
Install and authenticate the Spur MCP server in Cursor, Claude Code, Claude Desktop, Claude.ai, GitHub Copilot for VS Code, or ChatGPT using OAuth.
You can launch a guided setup directly from the Spur app. Go to **Integrations → MCP** and click **Setup** to open a step-by-step modal for your platform.
Authentication uses OAuth. When you connect for the first time, your browser will open to authorize access to your Spur account.
## Cursor
Click the button to install Spur directly in Cursor, or copy the deep link below and paste it into your browser address bar.
[](cursor://anysphere.cursor-deeplink/mcp/install?name=Spur\&config=eyJ1cmwiOiJodHRwczovL2FwcC5zcHVydGVzdC5jb20vYXBpL21jcCIsImhlYWRlcnMiOnt9fQ%3D%3D)
```
cursor://anysphere.cursor-deeplink/mcp/install?name=Spur&config=eyJ1cmwiOiJodHRwczovL2FwcC5zcHVydGVzdC5jb20vYXBpL21jcCIsImhlYWRlcnMiOnt9fQ%3D%3D
```
## Claude Code
Run this command in your terminal:
```bash theme={null}
claude mcp add Spur -- npx -y mcp-remote@latest https://app.spurtest.com/api/mcp
```
If you don't have `npx` installed, you can use the HTTP transport instead:
```bash theme={null}
claude mcp add --transport http Spur https://app.spurtest.com/api/mcp
```
## Claude Desktop and Claude.ai
Go to **Settings** and navigate to the **Connectors** tab. Claude.ai users can go directly to [claude.ai/settings/connectors](https://claude.ai/settings/connectors).
Click **Add custom connector**.
Set the URL to `https://app.spurtest.com/api/mcp`.
Complete the OAuth authorization flow. Your browser will open to authorize access to your Spur account.
## GitHub Copilot in VS Code
Make sure the GitHub Copilot extension is installed. Open the Copilot panel and navigate to the **MCP Servers** section.
Open the Command Palette (`Cmd+Shift+P` on Mac, `Ctrl+Shift+P` on Windows/Linux) and type **MCP: Add Server**.
Choose **HTTP (HTTP or Server-Sent Events)**.
Set the URL to `https://app.spurtest.com/api/mcp`.
Enter a server name — **Spur** is recommended.
Complete the OAuth authorization flow. Your browser will open to authorize access to your Spur account.
## ChatGPT
Choose **Settings** from the drop-down menu.
Click **Advanced Settings** under the **Apps** tab.
Toggle **Developer mode** on.
Click **Create app**.
Set the URL to `https://app.spurtest.com/api/mcp`.
Complete the OAuth authorization flow.
Verify the app was created successfully.
Select **Spur** from the Connectors list.
You're all set — start using Spur through ChatGPT.
# Triaging Test Plan Failures with MCP
Source: https://docs.spurtest.com/analysing-tests/mcp/spur-mcp-test-plans
Use the Spur MCP to run test plans, review every failure, and drill into root causes — without leaving your editor.
Test plans run your full regression suite across every environment and configuration in one go. When failures surface, you normally have to navigate the Spur UI to understand what went wrong for each test. With the Spur MCP, your AI agent can do this triage for you — pulling every failure, their reasons, and the detailed artifacts needed to diagnose each one. You can also create and update test plans directly from your editor.
## Available Tools
| Tool | What it does |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `list_test_plans` | Lists all test plans with suites, environments, and last run time. Pass `plan_id` to get the full editable configuration |
| `create_test_plan` | Creates a new test plan grouping suites and environments for coordinated execution |
| `update_test_plan` | Updates an existing test plan — name, description, environments, or suite configuration |
| `run_test_plan` | Triggers a full plan run across all configured suites and environments |
| `get_test_plan_runs` | Returns recent run history for a plan: timestamps, pass/fail counts, run IDs |
| `get_test_plan_run_overview` | Shows every test result in a run — failures first with failure reasons and `task_id`s for drilling in |
Once you have `task_id`s from `get_test_plan_run_overview`, use the standard run analysis tools to investigate individual failures:
* `get_test_run_overview` — Step-level failure summary for a specific task
* `get_test_run_screenshots` — Visual state of the browser at each step
* `get_test_run_console_logs` — JavaScript errors and browser warnings
* `get_test_run_network_logs` — HTTP requests and responses
## Common Workflows
### Create a new test plan
```
"Create a test plan called 'Nightly Regression' with the Checkout and Cart suites on Staging"
```
Claude calls `list_suites` and `list_environments` to resolve names to IDs, shows you a full plan summary, and waits for your approval before calling `create_test_plan` to save it.
### Update a test plan
```
"Add the Search suite to the Nightly Regression plan"
```
Claude first calls `list_test_plans` with the `plan_id` to get the current configuration, then shows you what will change and asks for approval before calling `update_test_plan`. When updating suites, the full new list replaces the existing one — so Claude copies across all existing suites and adds the new one.
### Trigger a regression run and wait for results
```
"Run the Regression test plan and let me know when it finishes"
```
Claude calls `run_test_plan` with the plan ID (discovered via `list_test_plans`) and then polls `get_test_plan_runs` to monitor progress.
### Triage all failures from the latest run
```
"What failed in the latest regression run?"
```
Claude calls `list_test_plans` to find the plan, `get_test_plan_runs` to find the most recent run ID, then `get_test_plan_run_overview` to list every failure with its reason.
### Deep-dive into a specific failure
```
"Look into the checkout failure from that run"
```
Claude takes the `task_id` from the failed test in the plan overview and calls `get_test_run_overview`, `get_test_run_screenshots`, and `get_test_run_console_logs` to build a full picture of why it failed.
### Full triage loop
For teams doing post-deploy validation, a complete triage looks like this:
```mermaid theme={null}
graph LR
A[run_test_plan] --> B[get_test_plan_runs]
B --> C[get_test_plan_run_overview]
C --> D[Failures list with task_ids]
D --> E[get_test_run_overview per task]
E --> F[Screenshots / Logs]
F --> G[Root cause]
```
You can ask Claude to work through every failure in one pass:
```
"Go through each failed test from the last regression run and tell me
whether it looks like a product bug or a test issue"
```
Claude iterates over each `task_id` from the plan overview, pulls the artifacts for each one, and returns a triage summary — distinguishing test issues (wrong selector, timing, stale step) from actual product regressions.
## Step-by-Step Example
```
"What test plans do we have?"
```
Claude calls `list_test_plans` and returns a list with plan IDs, suite counts, environment names, and the last run time for each.
```
"Run the Nightly Regression plan"
```
Claude calls `run_test_plan` with the plan ID. The run is queued and Claude confirms it has started.
```
"Show me the last 5 runs for that plan"
```
Claude calls `get_test_plan_runs` and returns a table of run IDs, timestamps, and pass/fail/error counts so you can pick a run to investigate.
```
"Give me a full breakdown of run 107272"
```
Claude calls `get_test_plan_run_overview`. Failures are listed first with their failure reasons. Each failure includes a `task_id` for deeper investigation.
```
"Dig into the cart failure — is it a product bug or a test issue?"
```
Claude uses `get_test_run_overview` and `get_test_run_screenshots` with the `task_id` to pull the step-level failure details and visual context.
## Tips
You can pass a run ID directly from a Spur URL. In `/test-plans/665/runs/107272`, the run ID is `107272`. Drop it straight into your prompt: "Give me the overview for run 107272."
Run a plan at the start of your day and ask Claude to triage every failure before your team standup. You'll arrive with a prioritized list of what needs attention and what's just noise.
When `get_test_plan_run_overview` reveals a test issue (not a product bug), ask Claude to fix it in-place: "Update the steps for that test to handle the new modal." Claude calls `update_test` to revise the steps without you leaving your editor.
# Shareable Links
Source: https://docs.spurtest.com/analysing-tests/shareable-links
Send a full Spur test result — steps, failure reasons, video replay, console logs, and network logs — to anyone via a shareable link with no login required.
## Overview
Shareable links let you send a full test result to anyone on your team without them needing a Spur account or being logged in. The recipient gets access to the complete result, including test steps, failure reasons, video replay, console logs, and network logs.
## How to share a test result
Navigate to any completed test run and click into the result you want to share.
Click the **Share** icon to generate a shareable link.
Copy the link and send it to anyone on your team. They can open it in any browser and view the full result immediately.
You can also pass shareable links to the [Spur MCP](/analysing-tests/mcp/spur-mcp) to analyze test results and help debug failures directly in your development workflow.
## What the recipient sees
The shared link gives full access to the test result, including test steps, video replay, console logs, and network logs.
### Test steps with Spur agent analysis
Click on each step to view the Spur agent's analysis, including what was executed and why it passed or failed.
### Video replay controls
Every test result includes a video replay of the test execution. The replay bar below the video provides these controls:
* **Play / Pause** — Click the play or pause button to start or stop playback. You can also click directly on the video to toggle.
* **Scrubber** — Drag the timeline scrubber to jump to any point in the recording. The scrubber preserves your current play/pause state: if the video is paused when you scrub, it stays paused at the new position. If it is playing, playback resumes automatically after you release.
* **Skip forward / backward** — Step through the recording in increments.
* **Playback speed** — Adjust the speed to review results faster or slow down for detailed inspection.
* **Fullscreen** — Expand the video for a closer look. All controls remain available in fullscreen mode.
* **Download** — Download the recording for offline viewing or sharing outside Spur.
### Console logs
Click the console log button in the video replay bar to view browser console output and JavaScript errors.
### Network logs
Click the network arrows in the video replay bar to inspect HTTP requests and responses captured during the test.
## Other ways to share results
You can also share test results by creating tickets directly from Spur:
Create Jira tickets from test failures with auto-populated details.
Generate Linear issues directly from test results.
# Spur AI
Source: https://docs.spurtest.com/analysing-tests/spur-ai-chat
Chat with Spur's built-in AI assistant to analyze runs, triage failures, and manage your testing workflow in natural language — without leaving the app.
## Overview
Spur AI is a built-in chat assistant available across the entire Spur app. Describe what you want to investigate, organize, or generate in plain language, and Spur AI works through it using your tests, suites, and run data.
There are two ways to use it:
* **Chat widget** — a persistent widget available on every page. Dock it to the side or float it as a compact panel. The widget picks up context from the page you're on, and your chat session follows you between pages.
* **Full-page view** — click **Spur AI** in the left sidebar to open the dedicated chat page with quick access to your recent sessions.
## What you can do
Ask for a summary of your recent runs to see how your tests have been performing without digging through run history.
Work through failures conversationally — Spur AI surfaces screenshots and logs so you can understand what went wrong and fix it.
Generate new tests from the material you provide, or ask Spur AI to help organize your existing tests.
Ask about your test coverage and overall test health to spot gaps and flaky areas.
## Sessions and context
Conversations are saved as sessions, so you can pick up where you left off. Recent sessions are one click away from both the widget and the full-page view, and an active session persists as you navigate — the widget carries your conversation from page to page and uses the current page as context for your questions.
## Attaching files and links
You can give Spur AI extra context by attaching material to your message:
* **Spreadsheets** — upload a CSV or spreadsheet, for example test input data
* **Documents** — upload PDFs such as specs or requirements
* **Jira tickets** — reference a ticket to give Spur AI its details
* **PRs or commits** — point Spur AI at a code change
* **Loom links** — share a recording as context
## Rich results
Spur AI renders results inline in the conversation — charts, screenshots, log viewers, and test run cards — so you can inspect outcomes without leaving the chat. For multi-step requests, a todo panel shows the tasks Spur AI is working through.
## Best practices
* **Keep each session focused on one topic** — scope matters. See [Using Spur AI Effectively](/analysing-tests/spur-ai-chat-best-practices) for how session length affects both answer quality and usage.
* **Reference tests by name** — the closer your phrasing is to the actual test or suite name, the more accurate the match.
* **Name environments explicitly** — include the environment (for example, "on staging") when your request targets a specific one.
* **Follow up on failures** — after asking what failed, ask how to fix it to get debugging context from logs and screenshots.
* **Attach data for context** — if your request depends on external material, attach the spreadsheet, document, ticket, or PR rather than describing it.
# Using Spur AI Effectively
Source: https://docs.spurtest.com/analysing-tests/spur-ai-chat-best-practices
Scope each conversation to one topic to keep Spur AI's answers sharp and your usage efficient.
## Why session scope matters
Spur AI works best when each session stays focused on a single topic — one failing suite, one triage question, one authoring task. Two things happen when a session drifts across unrelated topics:
* **Answer quality drops.** Every reply is generated with the full session history in view. Modern LLMs have finite context windows (roughly hundreds of thousands of tokens at the frontier, but effective recall degrades well before that limit — the "lost in the middle" effect). Once earlier messages, screenshots, and tool results start to crowd the window, Spur AI is more likely to conflate topics, miss recent details, or reason from stale context.
* **Usage grows fast.** Each turn re-processes the entire conversation so far. A session that started with one question and drifted through five more topics will cost significantly more per follow-up than a fresh session asking the same last question in isolation.
Both problems compound the longer a session runs.
## When to start a new session
Start a new session — don't continue the current one — when any of these are true:
* You're switching to a **different test, suite, or run** than the one you've been discussing.
* You're switching **modes** — for example, moving from triaging a failure to generating a new test.
* The current session is **long** (roughly 15–20 back-and-forth turns) and the next question doesn't depend on that history.
* You've attached large context earlier — spreadsheets, PDFs, PRs, Loom recordings — that isn't relevant to the next question.
* Spur AI starts **repeating itself**, contradicting earlier answers, or referencing the wrong test. That's a signal the effective context is saturated.
If the follow-up genuinely builds on the current thread ("now fix the failure you just described"), stay in the session. Continuity is the point of sessions — the goal isn't to open a new one every message, only to draw a clean line at topic boundaries.
## One session, one topic
Aim for a shape like:
* **Session A** — "Triage the checkout suite failures from last night's run on staging."
* **Session B** — "Generate a new test for the password reset flow from this spec." *(new session, attach the PDF here — not in Session A)*
* **Session C** — "Summarize test health for the mobile suite over the past week."
Each of those has a clear beginning, a bounded set of tests and data, and an end. When one is done, close it out and open the next.
## Keeping sessions efficient
Within a single session, small habits keep the context tight:
* **Lead with the specific target.** Reference the test, suite, run, or environment by name up front so Spur AI locks onto the right context on turn one instead of hunting for it across several messages.
* **Attach only what the current question needs.** Every attached spreadsheet, PDF, ticket, PR, or Loom sits in the session context from the moment you add it. Attach them in the session that needs them, not preemptively.
* **Ask one thing at a time.** Multi-part questions ("summarize the run, then generate three new tests, then open a Jira ticket") produce longer answers and longer follow-ups. Break them into separate turns, or separate sessions, and the whole thing runs cheaper and more accurately.
* **Wrap up before pivoting.** If you're about to change topics, ask Spur AI to summarize the outcome of the current thread first, then start a new session and paste the summary in if you need to carry anything forward. This is far leaner than dragging the entire history into the next topic.
* **Don't paste huge logs or transcripts inline.** Reference the run or attach the file — inline blobs sit in the context permanently and count against every subsequent turn.
## Signs it's time to start over
Open a new session when you notice:
* Replies are getting slower or shorter than earlier in the same session.
* Spur AI is answering the previous question instead of the current one.
* You're correcting the same misunderstanding more than once.
* The todo panel is carrying tasks from an unrelated earlier request.
Recent sessions stay one click away from both the chat widget and the full-page view, so switching sessions costs you nothing — and almost always improves the next answer.
# Test Overview Page
Source: https://docs.spurtest.com/analysing-tests/test-overview-page
Monitor and manage your test suite health with a centralized dashboard.
## Overview
The Test Overview page shows the latest result for each test across all your suites, giving you a bird's-eye view of your test suite health. You can quickly see how many tests passed, failed, raised warnings, or encountered errors, and drill into any category to investigate further.
This is also where you can manually classify failures and warnings.
Results are split by viewport, environment, and browser, so the same test may appear multiple times if it runs in different configurations.
## Most Recent Run Status
The Test Overview page always displays the most recent run status for each test:
* If a test failed previously but passed on its most recent run, it shows as **Passed**
* If a test was passing but failed on its most recent run, it shows as **Failed**
* Results reflect the current state of your application, not historical failures
The Test Overview page shows the most recent run result for each test. To view historical results or track how a test's status has changed over time, open the individual test run history.
## Test Status Categories
Each test on the overview page is assigned one of four statuses:
* **Failed** — The test did not meet its success criteria.
* **Warning** — The test completed but encountered non-critical issues.
* **Passed** — The test completed all steps successfully.
* **Error** — The test could not complete due to a system-level or execution issue.
## Warnings
Tests with a Warning status completed but encountered non-critical issues such as performance degradation or elements approaching threshold limits. These are worth reviewing to catch potential problems before they become failures.
For a warning you have already reviewed and accepted, use [Warning Suppression](/analysing-tests/warning-suppression) to keep it out of your results.
## Understanding Failures
Spur automatically categorizes failure reasons across all your folders and test plans. These categories are consistent regardless of which suite or test plan a test belongs to, making it easy to spot patterns across your application.
This cross-suite categorization helps you:
* Spot recurring failure patterns across different parts of your application
* Identify systemic issues that affect multiple test suites
* Prioritize fixes based on failure frequency and impact
# Test plan review
Source: https://docs.spurtest.com/analysing-tests/test-plan-review
Walk through every failure, warning, and error in a test plan run in Spur, triage each result, group by cause, and rerun failing tests without leaving the page.
After running a test plan, the review flow gives you a guided way to work through every failed test, warning, and error. You can triage each result, add notes, edit tests inline, create bug tickets, export PDFs, and pick up exactly where you left off across sessions.
## Starting a review
Open a test plan run from the run history. At the top of the results page you'll see the **Test Review** progress bar, which shows the number of tests remaining to review. This count includes failures, warnings, and errors.
Click **Start** to enter the review flow.
## The review interface
The review flow is split into two panels:
* **Left panel** — A list of all tests that failed, surfaced a warning, or encountered an error in this run
* **Right panel** — Full details for the selected test: failure reason, steps, screenshots, video, and console and network logs
Work through tests one at a time. As you assign a status to each test, it moves to the **Reviewed** tab. The left panel updates automatically so you always know what's left.
### Grouping the test list
Use the **Group by** dropdown at the top of the left panel to change how tests are organized:
* **Failure Reason** (default) — tests grouped by the root cause Spur detected
* **Folder + Suite** — tests grouped by folder, with a second level for each suite inside it
* **Environment** — tests grouped by the environment they ran against
* **Scenario** — tests grouped by scenario when the plan uses a scenario table
Your selection is saved in the URL, so sharing a link preserves the grouping for whoever opens it.
Use the **Expand all** and **Collapse all** control next to the dropdown to open or close every group at once — useful for scanning a large review list.
## Classifying tests
To assign a status, press C or click **Classify** in the action bar at the bottom of the screen. This opens the classify modal with four options:
**Bug** — Mark this when you have found a bug in your application.
**Closed** — Use this when the failure was expected or explained — for example, a deployment was in progress or the test environment was temporarily unavailable.
**Needs Rework** — Use this when the test steps themselves need to be updated. You can edit the test inline from within the review flow (see [Editing and rerunning tests](#editing-and-rerunning-tests) below).
**Needs Investigation** — Use this when you need more context before deciding — for example, you want to discuss the failure with a teammate before committing to a status.
You can quick-classify by pressing 1 through 4 while the classify modal is open.
The Reviewed tab groups tests into **Resolved** (Bug and Closed) and **Unresolved** (Needs Rework and Needs Investigation). Resolved tests are considered dealt with; unresolved tests still require follow-up action.
## Adding notes
You can attach a note to any test to record context, observations, or next steps.
* **Standalone note** — Press N or click **Note** in the action bar. Type your note and submit. Notes appear in the test timeline.
* **Note with classification** — While the classify modal is open, hold Shift and press a number key (Shift+1 through Shift+4) to assign a status and add a note at the same time.
Notes can also be added to multiple tests at once when using [bulk selection](#bulk-actions).
## Undo
Every classification action can be undone. After you classify a test, a toast notification appears with an **Undo** button. You can also press Cmd+Z (Mac) or Ctrl+Z (Windows/Linux) to revert the last action.
Undo restores the previous review status, removes any note that was created with the action, and returns you to the previous tab and selected test.
## Bulk actions
You can select multiple tests and apply actions to all of them at once.
1. Use the checkboxes in the left panel to select individual tests, or use the group-level checkbox to select all tests in a group.
2. The action bar changes to show the number of selected tests with a blue highlight.
3. From here you can:
* **Bulk classify** — assign the same status to all selected tests
* **Bulk notes** — add a note to all selected tests
* **Bulk PDF export** — export results for all selected tests
* **Bulk ticket creation** — create tickets for all selected tests
Press Escape to clear the selection.
## Keyboard shortcuts
The review flow supports keyboard shortcuts for fast triage.
| Shortcut | Action |
| --------------------------------------- | ----------------------------------------------------------------------------------------------- |
| C | Open or close the classify modal |
| 1 – 4 | Quick-classify (Bug, Closed, Needs Rework, Needs Investigation) when the classify modal is open |
| Shift+1 – Shift+4 | Classify with a note |
| N | Open the note input |
| S | Open the share menu |
| ← / → | Navigate to the previous or next test |
| Cmd/Ctrl+Z | Undo the last action |
| Escape | Clear bulk selection |
## Editing and rerunning tests
You can fix a test and re-run it without leaving the review flow:
With a test selected in the right panel, click **Edit**. The test side peek opens so you can update the steps.
Click **Save and Run**. A confirmation modal appears before the run starts. Spur saves your changes and triggers a new run.
A banner appears at the top of the panel showing when the test was edited and the rerun status. Once the rerun finishes, you'll see whether it passed or failed — giving you more context to finalize the status.
You can also open the **Run History** tab in the right panel to see all previous runs for the selected test in the same configuration (environment, browser, viewport).
### Rerunning native (mobile) tests
When you rerun a native test from the review flow, Spur automatically uses the correct native platform configuration from the original run. The run modal opens pre-configured with the matching platform (iOS, Android, or both) and environment, skipping directly to the summary step.
This means:
* **Web tests** rerun with the original browser and viewport
* **Native tests** rerun with the original native platform — no browser or viewport is applied
The rerun inherits the same environment and scenario configuration as the original test run. If the original test ran on Android with a specific environment, the rerun uses the same settings.
## Creating tickets
From within the review flow, you can file a Jira or Linear ticket for any test:
Click **Share** in the action bar (or press S) and select **Create a Ticket**.
Spur pre-populates the ticket with a failure reason, reproduction steps, test execution details, and a direct link to the test run. Edit any of these fields as needed.
Choose the project, priority, and assignee.
Click **Create Ticket**. The ticket identifier appears next to the test in the Reviewed tab, with a ticket icon to identify it at a glance.
Jira and Linear integrations must be connected before you can create tickets from the review flow. See the [Integrations guide](/analysing-tests/integrations/integrations) for setup.
## Exporting to PDF
You can export test results as PDF reports from the share menu:
* **Single test** — Click **Share** and select **Export PDF** to download a report for the currently selected test.
* **Multiple tests** — Select tests using [bulk selection](#bulk-actions), then use **Share** to export all selected tests in a single bulk PDF.
## Saving progress and resuming
You don't have to finish a review in one session. Click **Exit** at any time — your progress is saved automatically.
When you return to the test plan run page, the progress bar converts to a summary table showing all reviewed tests grouped by status. Tests with linked tickets show a ticket icon. You can re-enter the review flow from the summary to continue with the remaining tests.
The goal of the review flow is to reach zero unreviewed tests: every failure, warning, and error has been triaged so nothing slips through before a release.
# Warning Suppression
Source: https://docs.spurtest.com/analysing-tests/warning-suppression
Silence known warnings so they stop cluttering test results.
## Overview
During a run, the Spur agent raises warnings for issues that are not hard failures — a cosmetic glitch, a known noisy element, a quirk that exists only in staging. Some of these are already reviewed and accepted. Warning Suppression tells Spur to stop flagging them.
A suppression rule is created from a warning in a run. Spur saves the rule as a memory, clears the matching warnings in that run, and checks every later run against it.
## How suppression works
Suppression happens after a run finishes, not during it. A rule never changes what the agent does mid-run.
While the test runs, each warning shows as **Waiting on test to finish**. Spur has not classified it yet.
When the run ends, Spur checks each warning against every suppression rule whose scope covers that run's environment and test type.
A match shows as **Suppressed** on the step and no longer counts as a warning anywhere in Spur. Everything else becomes a normal warning.
Spur is deliberately conservative here. A suppressed warning is not deleted — it stays on the step and can still be expanded — but it no longer counts, and nobody goes looking for it. Because it is easy to miss, Spur suppresses only when it is confident the warning is the known issue the rule describes. A warning that raises a new concern about the same element stays visible.
## Suppress a warning
Expand the step that shows **Spur's Warning:**.
Spur AI opens in suppression mode and retrieves the full warning, the surrounding steps, and any screenshots or logs it needs. Nothing has to be pasted in.
Spur AI infers what to suppress from the run, and that inference is a starting point, not the final rule. Say what the rule should cover in the chat — which part of the warning is the accepted behavior, how broadly it should apply, which environments and test types belong in scope. A short instruction such as "only suppress this on the checkout page, not site-wide" produces a much more accurate rule than accepting the first draft.
Spur AI reads the existing memories first. When a rule already covers the warning, Spur AI names that rule instead of creating a duplicate. Otherwise it proposes a scope and asks about anything it cannot infer:
* **Environments** — the run's own environment, several environments, or All Environments, which also covers environments added later.
* **Test type** — Web (desktop, mobile, or both), Native (iOS, Android, or both), or every test type. Scope matters when a warning is viewport-specific: a mobile layout glitch should not be suppressed on desktop.
* **Breadth** — this exact case, or every case like it. Breadth lives in the wording of the rule.
Spur AI shows the exact text, the environments, and the test type before saving. Nothing is saved without approval.
Spur applies the new rule to the originating run, so that warning — and every other occurrence of it in the same test run — clears within seconds. Every later run is covered. Runs that finished earlier keep their warnings.
## Reading a suppressed warning
A suppressed warning stays on the step, collapsed, labeled **Suppressed**. Expanding the card shows the original observation. Hovering the label shows why Spur suppressed it and which memory it matched. The card also carries a **View Memory** link to the matched rule.
Two other states show up on the same card:
| Status | What it means |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Waiting on test to finish** | The run is still going. Spur classifies the observation once the test finishes. |
| **No Decision** | The run ended in an error before Spur could classify the observation. It was never promoted to a warning, so it does not count against the run. Re-run the test to get a decision. |
## Manage the rules
Suppression rules live on the **Memory** page in the sidebar. The table lists every rule with its environment, classification, how many times it has been used, and its creator. **Search memories** finds a rule by name.
Click a rule to open it:
* **Where this will be applied** — the classification, the environments, and the test type. The environments and the test type are editable in place.
* **Memory Description** — the rule text itself, per environment. Also editable in place.
* **Learned from** — the run the rule was created from.
* **Usage** — the tests this rule has suppressed warnings on, and how many times.
Delete a rule to stop suppressing the warnings it covers. Deleting cannot be undone, and past runs keep the classification they already have.
## Write rules that hold up
The rule text is what Spur matches against, so its wording decides how much gets suppressed.
One line, one known issue. "Do not flag 'Cancle' as a misspelling — it is the intended brand spelling." A multi-sentence explanation gives Spur more ways to read the rule, not fewer.
No run IDs, timestamps, or URLs. These never appear in the next run and only make the match less reliable.
Rule text is visible to everyone in the Application. Use [encrypted variables](/authoring-tests/test-side-peek/step-types/variables/encrypted-variables) for secrets in test steps, and keep them out of memories entirely.
"Do not flag the promo banner overlapping the nav on mobile web" suppresses one known layout issue. "Do not flag layout issues" also suppresses regressions nobody has seen yet.
Near-duplicate rules make matching unpredictable. When a rule almost covers a new warning, edit its scope or its text rather than creating another rule.
## Suppression vs snoozing
Both keep noise out of test results, but they act on different things.
* **Warning Suppression** hides one known warning while the test keeps running and keeps checking everything else. Use it for accepted behavior that will not change.
* [Snoozing](/managing-tests/snooze-tests) stops a test from running at all for a set period. Use it during a deployment, or while a known bug is being fixed.
# AI Test Generation
Source: https://docs.spurtest.com/authoring-tests/ai-test-generation
Spur's AI Test Generation accelerates test creation by automatically generating step-by-step tests or data-driven scenario tables from multiple input sources while transforming hours of manual test authoring into minutes of guided AI assistance.
## Overview
AI Test Generation enables you to create comprehensive test coverage quickly by leveraging existing test suites, uploading documentation or describing tests in plain language.
The AI analyzes your inputs and generates structured, executable tests that match your application's patterns and testing needs.
## What You Can Generate
Create one or more step-by-step tests from various sources including video recordings, Loom links, files or existing suite patterns
Generate data-driven scenario tables with variations based on your instructions, enabling parameterized testing across multiple data sets
## How to Use AI Test Generation
When you open AI Test Generation, select what you want to create - [Tests](/getting-started/first-test) or [Scenario Table.](/authoring-tests/scenarios/scenario-tables)
Provide context about your application to help Spur generate relevant, accurate results. Include information about your app's purpose, key features and user workflows.
Choose from three methods for generating tests, each suited to different workflows:
Leverage your existing test suite as a foundation for new tests. The AI analyzes your saved suites to understand your testing patterns and generates new tests that follow the same structure and style.
Upload test requirements, specifications, or documentation files to convert into structured test flows. The AI extracts test scenarios from your documentation and creates executable tests.
Describe your test in plain English and let the AI generate structured test steps. This method offers maximum flexibility for creating tests from scratch.
If you selected **Scenario Table** in step 2, provide instructions for creating data-driven test variations.
Scenario tables enable you to run the same test with multiple data sets, validating different user personas, product categories, or input combinations.
The AI processes your inputs and generates structured test steps ready for execution.
Review the generated tests, make any necessary adjustments, and click **Keep Tests** to add them to your test suite.
After generation, select which Test Suite to save your test to.
Your test will now appear in the selected Test Suite, ready for execution.
Review the generated test, add or verify the **Test URL** and click **Save**.
Your test will now appear in the selected Test Suite, ready for execution.
## Best Practices
* **Be Specific**: Provide detailed descriptions and context for more accurate test generation. Include information about expected behaviors, user flows, and validation points.
* **Reference Existing Suites**: When available, reference similar test suites to help the AI understand your testing patterns and preferred structure.
* **Iterate and Refine**: Review generated tests and provide feedback through additional instructions to improve results.
* **Start Simple**: Begin with straightforward test scenarios before generating complex multi-step flows.
* **Use Descriptive Names**: Clear test names improve organization and make results easier to understand.
## Limitations
* Maximum 10 tests per generation run
* Generated tests may require manual review and adjustment
* Complex authentication flows may need additional configuration
* File uploads support PDF, CSV, and Markdown formats only
# Caching Tests
Source: https://docs.spurtest.com/authoring-tests/caching-tests
Cache test results for faster subsequent test runs and improved execution efficiency.
## Enable Caching
When creating or editing a test, locate the **Advanced Configurations** section and check the **Cached** checkbox under it.
To disable caching, simply uncheck the box. By default, tests are not cached.
## How Caching Works
When caching is enabled, the Spur Agent stores successful test execution data. On subsequent runs, cached results are reused when test configuration remains unchanged, significantly reducing execution time and resource consumption.
**Benefits:**
* Faster test execution for unchanged tests
* Reduced load on testing infrastructure
* More efficient use of test run quotas
## When to Cache Tests
Caching accelerates tests with stable early steps, but becomes counterproductive when variability occurs early in the sequence.
### When Caching Works Well
Tests with consistent initial sequences (login, navigation, data preparation) followed by randomization later benefit most.
Cache tests when you anticipate few changes to cached steps and have confirmed test stability through at least one successful run.
### When NOT to Cache
Random elements in early steps (such as product selection at step 2) create cascading changes through subsequent steps, preventing cache hits entirely.
Tests with multiple random or dynamic elements become slower with caching enabled. Poor caching strategy adds overhead from failed cache attempts while still requiring full execution.
### Key Decision Point
Identify where variability begins in your test sequence. Early variability makes caching counterproductive; late variability maximizes cache efficiency.
## Editing a Test After a Cached Run
Caching automatically manages edited tests and steps. When you edit a test after a cached run, the Spur Agent successfully invalidates the cache and runs the test with fresh execution. This ensures your changes are properly validated without manual cache clearing.
# Dependencies
Source: https://docs.spurtest.com/authoring-tests/dependencies
Test dependencies in Spur allow you to define relationships between tests and control their execution order.
## Overview
Dependencies ensure tests run in the correct sequence, maintain proper state management, and handle cleanup operations effectively.
Dependencies are only contained within a [Test Suite](/managing-tests/suite). Tests in different suites cannot have dependency relationships.
## Types of Dependencies
Parent dependencies ensure tests run sequentially, where child tests only run if the parent test passes.
**How Parent Dependencies work:**
* Tests run in the order specified by the dependency arrows
* Each test can only have one parent
* If a test fails, subsequent tests will not run (except for teardown tests)
* Each test must complete before the next one begins
* This ensures data consistency and proper state management between tests
Teardown dependencies are cleanup tests that always run regardless of whether their connected test passes or fails.
**How Teardown Dependencies work:**
* Teardown tests can connect to multiple parent tests
* They always run regardless of connected test pass/fail status
* Ensures proper cleanup and resource management
* Prevents resource collision on subsequent test runs
## How to Connect Dependencies
Navigate to your Test Suites and select the suite where you want to add dependency relationships between tests.
Click on a test to open the test side peek window, which displays the test details.
From Test Details, switch to the Flow View tab. This is where you configure test dependencies and teardown options.
Determine which tests should have dependency relationships.
For example, identify your parent test like "Add Items to Cart", child tests such as "Complete Checkout" and "Add Second Item to Cart", and your teardown test like "Clear Cart and Logout".
Configure the parent-child relationship between tests to control execution order.
Open the test you want to add as your child. For example, open "Complete Checkout" test.
Switch to the Flow View tab within the test side peek window.
Click "Add Dependency" and select the test you want to make your parent.
For example, select "Add Items to Cart" from the dropdown.
Click Save Test to apply the parent dependency configuration.
Configure a test to function as a teardown test that always runs regardless of other test results.
Open the test you want to designate as the teardown test. For example, open "Clear Cart and Logout" test.
Navigate to the Flow View tab in the test side peek window. **Check the box** to mark this test as a teardown test and **click Save Test** to apply the teardown designation.
Link your teardown test to the tests that need cleanup operations.
Navigate to the test you want this teardown test to connect to. For example, open "Add Items to Cart" test. Switch to the Flow View tab within the test side peek window.
Click the dropdown menu for "Add a Teardown Test" and select your designated teardown test from the list.
Click Save Test to establish the teardown connection.
After saving all tests, navigate to the Flow View of the test suite.
You will now see visually how your test dependencies work, showing the execution flow from parent to child tests and teardown connections
## Connection to Snoozed Tests
Snoozed tests are temporarily disabled tests that won't run in your test suite. When you snooze a test that has dependencies:
* Child tests dependent on the snoozed test will not run
* The entire dependency chain below the snoozed test is paused
* This prevents failures from tests that depend on setup from the snoozed test
To resume the dependency chain, unsnooze the parent test.
# Overview of Environments
Source: https://docs.spurtest.com/authoring-tests/environments/environments
Run tests across multiple environments with environment-specific configurations for comprehensive application validation.
## What are Environments?
An environment represents a specific deployment of your application where tests can be executed.
**Common examples include:**
Your local or dev server for early-stage testing
Pre-production environment for final validation before release
Live production environment for monitoring real user experiences
Temporary environments for testing new features in isolation
Each environment can have its own URLs, credentials, and configuration variables, which automatically apply when a test runs in that environment.
Choose a Default Environment to streamline test configuration and speed up the test run setup process.
## Key Benefits
Write tests once, run them across all environments without copying test code.
Compare test results across environments to identify environment-specific issues.
Run the same test across multiple environments simultaneously for faster validation.
Each environment has its own URLs, credentials, and variables that automatically apply.
Need to temporarily redirect tests to a deploy preview or feature branch URL without changing your environment settings? Use [Override URLs](/running-tests/cicd/override-urls) to redirect at runtime.
# Properties
Source: https://docs.spurtest.com/authoring-tests/environments/properties
Environment-specific variables that store configuration values like URLs, credentials, API keys, and custom settings. Properties enable tests to adapt automatically based on the environment they're running in.
## What are Properties?
Environment variables allow you to parameterize your tests with environment-specific values like URLs, credentials, API keys, and configuration settings. Properties are key-value pairs associated with specific environments that automatically apply when tests run in those environments.
## Variable Types
Store base domains and full URLs for your application.
URL variables are validated to ensure they're valid URLs. They must include the protocol (http\:// or https\://).
Store a username and password combination to be used in all HTTPS requests.
Encrypted variables to store values useable in test steps.
Secret variables are write-only after creation. You can replace them but cannot view the current value.
Custom HTTP headers sent with every request in that environment.
Headers are useful for feature flags or routing requests to specific backend services.
## How to Create Properties
Navigate to the Environments page and switch from the **Web URL tab** to the **Properties tab**.
Click the **+ Add Property** button at the extreme right to begin creating a new property.
Select a property type - **Header, Variable or HTTPS Configuration**. Each type serves different purposes as explained in the Variable Types section above.
Enter a descriptive name for your property and click **Create Property**.
All configured environments will display in the table. For each environment, set whether the property is required and enter the appropriate value.
Mark a variable as required for each environment to specify if the environment must have a value for the variable.
**Required Variables** must have values in all environments before tests can run.
**Optional Variables** can be left empty in some environments, allowing tests to run without them.
**Note:** You can also apply the same value to other properties automatically by clicking Apply value to all environments option
Click **Create Property** and a new property is created. This is available to all tests running in the configured environments.
Once created, properties automatically apply to tests running in their configured environments.
The Spur Agent uses the appropriate property value based on which environment the test executes in.
## Best Practices
* **Use descriptive names**: Make property names self-explanatory for team collaboration
* **Mark required properties appropriately**: Only mark properties as required if tests cannot run without them
* **Use Secrets for sensitive data**: Store passwords, API keys, and tokens as Secret variables for security
* **Validate URL variables**: Ensure all URL variables include the protocol (https\://)
* **Document property purposes**: Add clear descriptions when creating properties to help team members understand their use
* **Apply values across environments strategically**: Use "apply to all environments" only when values are truly universal
# Mobile Streaming
Source: https://docs.spurtest.com/authoring-tests/mobile-streaming
Open a live, interactive mobile session in your browser to explore your app, reproduce issues, and try out steps before writing a test.
## What is Mobile Streaming?
Mobile Streaming gives you a live, interactive view of a mobile device running your app, right inside your browser. You can tap, type, and scroll on the streamed screen exactly as you would on a real phone — no local setup, emulator, or cables required.
Use it to:
Click through flows to see how the app behaves before writing any tests.
Walk through the steps that led to a problem and watch it happen live.
Try out a flow, then describe those same steps when authoring a test.
Open the app for a specific environment and confirm it looks right.
## Start a streaming session
Go to **Environments** and find the environment whose app you want to open.
Select **Stream** on that environment. Spur opens the streaming view with the environment already selected for you.
The live device takes a few moments to start. Once it's ready, the app opens on the streamed screen.
## Interact with the streamed device
Once the session is live, interact with the screen just like a real phone:
* **Tap** anywhere on the screen to select buttons, links, and fields.
* **Type** using your keyboard when a text field is focused.
* **Scroll** to move through lists and pages.
Give the screen a moment to catch up after each action — the streamed view reflects what's happening on the device in real time, so there can be a short delay.
## End the session
When you're finished, stop the streaming view to end the session. Ending the session frees up the device and stops the session from running.
Streaming sessions consume mobile credits. A session is only counted toward your usage once it has been active for **at least 2 minutes** — short sessions below that threshold are not billed.
# Preview Editor
Source: https://docs.spurtest.com/authoring-tests/preview-editor
The Preview Editor provides an interactive test authoring environment where you can write, execute and debug test steps in real-time.
## Overview
The **Preview Editor** combines test authoring with live execution feedback, allowing you to validate test steps as you write them.
The **Spursor (Spur Cursor) AI agent** executes your instructions in a live browser environment, providing immediate visibility into how your tests perform.
## Getting Started
Navigate to the test you want to edit and click **Open in Preview Editor**.
Select the viewport for your test session - either Desktop or Mobile. This determines the screen dimensions the Spursor agent will use during test execution.
You can reference the [Viewports](/authoring-tests/test-side-peek/viewports) for detailed information on viewport configurations.
The Preview Editor launches an interactive test authoring environment with multiple capabilities accessible through different tabs and panels.
## Navigating the Editing Environment
This section onsists of several key components that work together to provide comprehensive test authoring and debugging capabilities.
Write and execute test steps in the left panel. The editor supports adding, editing, and running individual steps or complete test sequences.
Configure test dependencies and tear down tests to control test execution order. The Dependencies panel allows you to establish relationships between tests.
Configure test metadata and expected outcomes in the Details panel. This section allows you to add descriptive information about your test.
Watch the Spursor AI agent execute your test steps in real-time within a live browser environment. The sandbox displays exactly what the agent sees and does during test execution.
User interactions in this sandbox are not recorded. Any changes made by the user in this sandbox browser will not be incorporated into testing.
Preview Mode allows you to review the Spursor agent's planned actions before execution.
View the Spursor agent's thought process when evaluating and executing test steps. Agent logs provide insight into how Spursor interprets your instructions and decides on actions.
View real-time console logs generated when running tests, including warnings, errors, and debug messages from the browser.
View real-time network activity during test execution, including API requests, response status codes, methods, and domains.
View extracted or generated values saved in the testing environment. These values can be accessed and used in subsequent test steps.
Access page and window dimensions to aid test step creation. View current scroll position, page dimensions, and window size. You can also scroll within the Spursor Sandbox and access the page position directly.
View technical session information and connection status for the test execution environment. The Admin tab displays session initialization details, WebSocket connections, and other backend communications.
View the complete action history for your test session. The Actions tab displays all actions performed by the Spursor agent during test execution.
## Key Benefits
Preview Editor allows you to walk through the agent's exact execution process, identifying and resolving issues with test steps in real-time.
Provides complete visibility into how Spursor interprets and executes your instructions, helping you understand the AI agent's decision-making process.
By observing how the AI responds to different instructions in real-time, you can improve your prompting skills and learn the most effective ways to communicate with the agent.
Preview Mode ensures that each step executes exactly as intended, reducing errors and improving test reliability. You maintain full control over the agent's actions before execution.
# Scenario Tables
Source: https://docs.spurtest.com/authoring-tests/scenarios/scenario-tables
Parameterize Spur tests with reusable scenario tables so one test runs across multiple data rows instead of duplicating nearly identical test cases.
## What are scenario tables?
Scenario Tables are a powerful feature in Spur that help you simplify and scale your test suites by using parameterized test data. Instead of creating multiple nearly identical tests with different inputs, you can write one test that dynamically runs through multiple scenarios defined in a table.
**Understanding the structure:**
* Each **row** = one scenario (test variation)
* Each **column** = one property (variable you'll use in tests)
## How to set up scenario tables
### Step 1: Create your scenario table
Navigate to the **Scenario Tables** section in Spur and choose your preferred method:
Best for small datasets
Click the New Scenario button
* **Scenario Table Name**: Choose a descriptive name
* **Description**: Explain what scenarios this table covers
Click "Create Scenario"
Add your data manually in the table editor
Click "Save Edits" when finished
Recommended for bulk data
Click the Import via CSV button in the Scenario Tables section
Follow this format:
**Important CSV requirements:**
* First column must be "Scenario Name"
* Property names cannot contain spaces
* Each property name must be unique
* Use underscores instead of spaces for column names (e.g., `user_email` instead of `user email`)
* Enter **Scenario Table Name**
* Add a clear **Description**
* Review the preview to confirm correct import
Click "Import" to create your table
### Step 2: Connect your table to a test
Scenario Tables must be connected to **Test Suites**, not individual tests. Once connected to a suite, all tests within that suite can use the scenario properties.
#### How it works
1. **Connect** the Scenario Table to a Test Suite
2. **Use** the properties `[property_name]` in any test within that suite
3. **Run** the suite to execute all scenarios across all tests
Now you'll connect your Scenario Table to a test suite. You can do this in two ways:
#### Option 1: Through the Test Suites menu
Navigate to the Test Suites section
Choose the test suite you want to connect to a scenario table
Click the three-dot menu (⋯) next to your test suite
Select "Connect Scenario Table" from the dropdown menu
Select the scenario table you want to connect to this test suite
#### Option 2: Through the test editor
Open the test editor for your chosen test
In the test editor:
* Type `[` to open the scenario variable menu
* Select your Scenario Table (e.g., "Flight List Table")
* Insert properties into test steps (e.g., "Type \[From\_city]")
Property names will auto-complete as you type, making it easy to reference your scenario data.
[Detailed guide for using Scenarios in Tests →](/authoring-tests/scenarios/scenarios)
### Step 3: Run and monitor your tests
After saving your scenario-based test:
Click "Run" to execute all scenarios
Check results in Run History, broken down by scenario:
* Example: Separate results for DFZ scenario and LAX scenario
Click each scenario to inspect individual steps and outcomes
Schedule recurring runs just like regular test suite
***
## Searching scenarios
When selecting scenarios to run, you can search across **all property values** — not just the scenario name. Type any value that appears in your table and matching scenarios will be filtered and highlighted instantly.
This is especially useful for large scenario tables where you need to quickly find a scenario by one of its data values — for example, searching by city name, email, or any other property.
## Managing scenarios
Use the toggle switch in the Status column to enable or disable specific scenarios without deleting them. Disabled scenarios won't run when you execute the test.
Click any cell in the scenario table to edit values directly. Changes save automatically.
Click **+ New Scenario** at the bottom of the table or press the keyboard shortcut to add additional scenario rows.
Select scenarios and use the delete option to remove them from your table.
## Best practices
* **Start simple**: Begin with 2-3 scenarios to validate your test logic before scaling up
* **Use descriptive scenario names**: Make it easy to identify which scenario failed in test results
* **Organize related scenarios together**: Group similar test variations in the same scenario table
* **Keep variables consistent**: Use the same variable names across related tests for easier management
* **Test with one scenario first**: Verify your test works correctly with a single scenario before adding more
* **Document edge cases**: Use scenario names to clearly indicate boundary conditions or special cases
## Key benefits
Write one test instead of many duplicate tests. A single parameterized test can handle dozens of scenarios without duplicating test logic.
Update inputs in one central location. When test data needs to change, modify the scenario table rather than updating multiple individual tests.
Easily test variations and edge cases. Add new scenarios to your table without modifying test logic, enabling comprehensive coverage of input combinations.
Easily test variations and edge cases. Add new scenarios to your table without modifying test logic, enabling comprehensive coverage of input combinations.
***
# Reference scenario table properties in test steps
Source: https://docs.spurtest.com/authoring-tests/scenarios/scenarios
Insert scenario table properties into Spur test steps with the `[` shortcut to build data-driven tests that iterate through every row automatically.
## Using scenario properties in a test step
Once you've connected a **Scenario Table** to a test, you can use its properties directly in your test steps to create dynamic, data-driven tests.
### Property insertion with `[`
In the test step editor, type the `[` key to trigger the **Scenario Property Menu**. This menu will show all available properties from the Scenario Table you've linked to this test.
For example, if your table contains:
Typing `[` will let you choose between:
* `From`
* `From_city`
* `To`
Once selected, the property will appear in your test step like this:
When the test runs, Spur will replace `[From_city]` with the actual value from each scenario row—for example:
* In Scenario 1 `DFW - ATH`: `Type Dallas-Fort Worth`
* In Scenario 2 `LAX - CDG`: `Type Los Angeles`
This allows a single test to dynamically adapt to multiple data inputs.
### Mid-step insertion with `/`
You can also insert scenario properties and other variables **in the middle of existing step text** by typing `/` at any cursor position. This opens the **Shortcuts Menu**, which in mid-step mode includes:
* **Scenario** — Insert a scenario table property at the current cursor position
* **Insert Variable** — Insert an environment variable at the current cursor position
* **Email** — Insert an email inbox reference at the current cursor position
Select **Scenario** from the menu to open the Scenario Property Menu and choose a property to insert at the cursor—without rewriting the step from scratch.
Use `[` when you want to insert a scenario property at the start of a step or on its own. Use `/` when you need to embed a variable or scenario reference in the middle of existing step text.
### Preview and validation
* You can preview a set of property values for a specific scenario by clicking the **scenario preview icon** (\[ ]) in the test editor.
* Before running the test, you can preview with different scenarios to ensure that the values are represented correctly.
### Scenario-activated test icon indication
Once you add a scenario step to the test, you can confirm that the test is a scenario test by verifying the icon for the test changes to the one in the image.
### Tips
* Use clear column headers in your CSV—they become your property names.
* Make sure each property is referenced with square brackets (e.g. `[From_city]`), or it won't be substituted at runtime.
* You can mix static and dynamic values in a step:\
`Verify this text "Searching flights" exists next to [From_city] and [To]`
# Advanced Configurations
Source: https://docs.spurtest.com/authoring-tests/test-side-peek/advanced-configurations
Change your browser's locale, network speed and HTTPS credentials to test your application under different conditions.
## What are Advanced Configurations?
Advanced Configurations provide powerful capabilities for testing scenarios including A/B testing, header modifications and internal logic validation.
Configure these settings in Test Editing Side Peek and customize the test execution environment with browser settings, network conditions and HTTP request modifications.
## Configuration Options
### Locale
Set browser language and region to test internationalization. Use for testing multi-language support, region-specific content, or currency formatting.
**Use cases:**
* Testing multi-language product descriptions
* Validating currency formatting (USD, EUR, JPY)
* Testing region-specific content
### Network Throttling
Simulate different network conditions including packet loss. Use for testing performance on slower connections and validating loading states.
* None (default)
* Fast 4G
* Slow 4G
* 3G
* Offline
* Custom
* None - 0% (default)
* Low - 2%
* High - 5%
* Extreme - 10%
**Use cases:**
* Testing application behavior on mobile networks
* Validating loading states and timeouts
### Headers
Add custom HTTP headers to requests. Default headers from your environment appear first, followed by any additional headers you add.
**Use cases:**
* Adding authentication tokens
* Setting custom API headers
* A/B testing with custom headers
### Mock Network Call
Configure route overrides to intercept and modify network requests during test execution, enabling you to mock API responses, redirect requests or inject test data.
**Use cases:**
* **Mock API endpoints to control test conditions:** Override backend responses to ensure consistent test behavior. For example, mock a checkout endpoint to return a successful order confirmation, allowing you to test post-purchase flows without processing real transactions.
### HTTPS Credentials
Configure HTTP basic authentication credentials for tests that require authentication. Default HTTPS credentials from your selected environment are shown first. Only one credential can be selected per test.
**Use Cases:**
* **Testing password-protected staging environments:** Authenticate automatically to staging sites that require HTTP basic auth before the Spur Agent begins test execution
* **Accessing internal development servers:** Bypass authentication prompts on internal servers during automated testing without exposing credentials in test scripts.
* **Validating authentication flows:** Test that proper authentication is required and that invalid credentials are rejected as expected.
# Login States
Source: https://docs.spurtest.com/authoring-tests/test-side-peek/login-states
Manage authentication across your tests efficiently by reusing login sessions and avoiding redundant authentication steps.
## What are Login States?
Login states in Spur allow you to manage authentication across your tests efficiently. Authentication is a crucial part of many test scenarios.
Spur provides flexible options to handle authentication states across your tests, enabling you to start tests from authenticated states or save login states for reuse. Configure these settings in Test Editing Side Peek.
## Before and After Login States
Without login states, every test that requires authentication must include its own login steps, adding redundancy and slowing down execution. With login states, you save a login session once and reuse it across tests, so they skip straight to the actual workflow.
## How to Configure Login States
During test creation in Test Side Peek, check below for more information about Login States options.
Select the appropriate login state option based on your testing needs.
Begin this test using the login state from another test. This allows tests to skip login steps and start directly from an authenticated state, reducing execution time and improving test efficiency.
You can also use Scenario Tables to organize and select login tests directly, streamlining authentication management across multiple test configurations.
**How it works:**
1. Check "Start from logged-in state"
2. Select a login test from the dropdown
3. Your test will begin with the authentication state from the selected test
* Tests that require an authenticated user
* Avoiding redundant login steps
* Maintaining consistent test state
Make this test's login state available for other tests to use. Ideal for creating dedicated login tests that other tests can reference.
Login states are saved at the end of test execution and can be used by other tests that select this test as their login state source.
**How it works:**
1. Check "Save login state for other tests"
2. Complete your login test
3. Other tests can now select this test as their login state source
* Creating reusable login tests
* Making authentication states available across test suites
* Reducing test execution time
## Parallel Test Execution with Multiple Accounts
When running tests in parallel, it's recommended to use different accounts for different test suites to prevent state interference.
**This ensures:**
* Tests can run simultaneously without affecting each other's states
* Each test suite has its own isolated authentication context
* Changes made in one test suite won't impact the others
* You can maintain predictable test behavior in parallel execution
## Best Practices
**Create Dedicated Login Tests**
* Make separate tests for different user roles
* Keep login tests focused and minimal
* Use clear naming conventions (e.g., "Admin Login", "Customer Login")
**State Management**
* Save login states from tests that perform authentication
* Reuse login states to reduce test execution time
* Consider test dependencies when managing states
**Security Considerations**
* Use environment variables for credentials
* Regularly update saved login states
* Clear authentication data in teardown tests when needed
If you're experiencing issues with authentication in custom configurations, please reach out to the Spur team. We're here to help optimize authentication for your specific setup.
# Script to Test Generation
Source: https://docs.spurtest.com/authoring-tests/test-side-peek/script-to-test
Import existing Playwright, Selenium or other automation scripts and transform them into Spur test steps that can be executed with the Spur Agent.
## Overview
Script to Test Generation bridges the gap between traditional automation frameworks and Spur's natural language testing approach.
By importing scripts, you can quickly migrate existing test coverage to Spur without manual rewriting, while maintaining the test logic and validation steps you've already developed.
**Supported Script Types:**
* Playwright scripts (.js, .ts)
* Selenium scripts (.py, .js, .java)
* Cypress scripts (.js)
* Puppeteer scripts (.js)
## How to Generate Spur Tests from Scripts
Open your Spur Dashboard. Click **New** and choose **Test** from the dropdown menu to begin the test creation process.
Enter a name for your test and add it to an existing Test Suite or create a new one. Click **Create Test** to proceed.
The Test Editing Side Peek will open and fill in the Test URL field. Reference [Environments](/authoring-tests/environments/environments) for configuring environment-specific URLs.
Locate the **Auto-generate** button in the Test Steps section and click **From Code** to access the script import feature.
The **Import Test from Script** modal will appear. Choose your script file and click **Import Steps** to begin the conversion process.
All imported test steps now appear in the Test Editing Side Peek. Configure viewport settings, [Advanced Configurations](/authoring-tests/test-side-peek/advanced-configurations), and caching options as needed. Reference [Create Your First Test](/getting-started/first-test) for detailed guidance on these settings.
Click **Save Test** when complete.
Your test from script has been created successfully. Navigate to the test suite where you saved your test to view, run, or edit it.
## Best Practices
1. **Review all imported steps**: Always verify that converted steps match your testing intent. The AI conversion is highly accurate but may require minor adjustments.
2. **Leverage Preview Editor**: After import, use the [Preview Editor](/authoring-tests/preview-editor) to validate and refine test steps with live browser feedback.
3. **Maintain test organization**: Import scripts into appropriate test suites to maintain clear test organization and facilitate team collaboration.
# Overview of Supported Actions
Source: https://docs.spurtest.com/authoring-tests/test-side-peek/step-types/actions/actions-overview
All available discrete actions you can use in your test steps.
Trigger interactions on buttons, links, checkboxes, and other elements. Supports single click, double click, and right click.
Move the cursor over elements to reveal dropdown menus, tooltips, and nested navigation.
Navigate through content vertically or horizontally, including inner scrollable containers.
Choose options from system or custom dropdowns using click or typing interactions.
Pause execution to allow for page loads, animations, or data processing before the next step.
Enter text into form fields, search boxes, and other input elements.
# Click
Source: https://docs.spurtest.com/authoring-tests/test-side-peek/step-types/actions/click
Simulate click interactions on elements across your application.
## Overview
The click action triggers an interaction when the agent presses on a specific element. Spur supports standard left clicks, double clicks, and right clicks.
## Click Types
Standard left click for buttons, links, checkboxes, and other interactive elements.
Double left click for selecting text, opening items, or triggering edit modes.
Right click to open context menus or access additional options on an element.
## Common Use Cases
## Best Practices
* Be specific in your element descriptions so the agent can reliably identify the correct target
* Include surrounding context when targeting dynamic elements
* Consider using a [Wait](/authoring-tests/test-side-peek/step-types/actions/wait) action before clicking on content that loads dynamically
* Verify the click result when the interaction is critical to the test flow
Avoid generic descriptions like "Click the button". Always provide enough context for the agent to identify the correct element.
## Troubleshooting
If the agent cannot find the element:
* Check if the element is visible in the viewport
* Ensure the description matches what is displayed on screen
* Add more context such as nearby text or section names
* Use a Wait action if the element loads dynamically
If the agent clicks the wrong element:
* Add more specific context to distinguish the target
* Include nearby text or landmarks
* Specify the element type explicitly (e.g. "Click the Submit button" instead of "Click Submit")
# Hover
Source: https://docs.spurtest.com/authoring-tests/test-side-peek/step-types/actions/hover
Simulate mouse hover interactions for dropdown menus, tooltips, and other interactive elements.
## Overview
The hover action moves the mouse cursor over a specific element on the page. This is essential for interacting with dropdown menus, tooltips, nested navigation, and scrollable containers.
## Basic Usage
Move the cursor over any element by describing it in natural language.
## Common Hover Combinations
Hover actions frequently work in combination with other actions.
### Hover then Scroll
Use hover to position the cursor over a scrollable container before scrolling within it.
Keep the cursor over the container while scrolling. Use specific pixel values for scroll amounts and add Wait actions if needed for smooth interactions.
### Hover for Dropdown Menus
Hover over a dropdown trigger to reveal its contents, then interact with the revealed options.
### Hover for Nested Menus
Hover over a parent menu item, wait for the submenu to appear, then hover over the submenu items.
# Scroll
Source: https://docs.spurtest.com/authoring-tests/test-side-peek/step-types/actions/scroll
Learn how to use scroll actions in Spur
The scroll action allows you to navigate through content by moving vertically or horizontally on a webpage.
## Basic Usage
Scroll vertically and horizontally using natural language.
## For Inner Scrolls
For scrollable containers within a page, first hover on the container, then scroll. You can also describe the inner scroll directly:
```
Scroll up in the chat history to view the results
```
## Scroll Until Visible
You can tell the agent to scroll until a specific element comes into view:
```
Scroll down until the "favorites" section is visible
```
This is useful when you need to reach a section of the page but don't know exactly how far to scroll.
## Scroll to Page Sections
You can tell the agent to scroll directly to the footer or header of a page:
```
Scroll down to the footer of the page
```
## Best Practices
The Spur agent decides how far to scroll based on your prompt. If the prompt is to scroll all the way to the bottom of the page, the agent will scroll by a larger amount (e.g. the entire viewport).
For more reliable tests, provide specific pixel values for scroll distances when precision matters.
# Select
Source: https://docs.spurtest.com/authoring-tests/test-side-peek/step-types/actions/select
Choose options from system and custom dropdowns.
## Overview
The select action handles dropdown interactions. The approach differs depending on whether the dropdown is a native system element or a custom-built component.
## System Dropdowns
Use the select action for native browser dropdowns (HTML `