Skip to main content

​
Overview

Spur uses an AI agent to interact with your web application the same way a human tester would. The agent sees the page, reads visible text, and performs actions based on your instructions. The key shift from traditional QA is moving from selector-based testing to intent-based testing. Instead of writing brittle locators tied to implementation details, you describe what you want the agent to do in plain English.
Write each step as though you are instructing a colleague who is looking at the screen.
  • Use plain English
  • Do not include code, CSS selectors, XPath, or DOM attributes
  • Describe elements by what a user can see, not by how they are built

​
General Guidelines

These guidelines apply across all step types — action, verify, and extract.

​
Keep the Viewport in Mind

Page layouts differ between desktop and mobile viewports. Elements may appear in different positions, behind menus, or require different scroll distances. If your test runs on both viewports, confirm that each step works on both.

​
Ensure Content is Visible

The agent can only interact with or observe elements that are currently visible on screen. Before any action, verification, or extraction, make sure the target content is in view. If it requires scrolling, clicking, or expanding a section to appear, perform those interactions first as separate steps.

​
Writing Action Steps

The action agent performs user interactions on the page: clicking, typing, scrolling, hovering, selecting, and waiting.

​
Intent-Based Prompting

Describe what you want to happen, not how to do it. Focus on the intent and the stable, visible parts of the element.
Instead of thisWrite this
Click on the element with class “btn-primary” at position (340, 520)Click the Submit button at the bottom of the form
Find the input field and clear it, then type the valueType “New York” in the City field
Click the element with data-testid “search-input”, verify it has focus, type the value, then check the field is populated and suggestions appearClick the Search field, type “Running Shoes”, and verify that search suggestions appear
Only encode stable parts of the element in your description. Avoid including dynamic values (like prices or counts) that change between runs. Focus on labels, positions, and surrounding landmarks that stay consistent.
You can combine multiple form-filling actions into a single step when they are on the same form. This speeds up test execution. 
Enter "John" in the First Name field, "Doe" in the Last Name field,
and "john.doe@example.com" in the Email field

​
Scrolling

The agent only interacts with elements that are currently visible in the viewport. If the element you need is off-screen, include an explicit scroll step. 
Scroll down to the "Reviews" section

Scroll down until the "Submit" button is visible
Including scroll instructions before actions or verifications improves test stability, even though the agent can sometimes find off-screen elements. See Scroll for more details.

​
Writing Verify Steps

The verification agent is a visual assertion agent. It looks at the current state of the page and checks whether your assertion is true. It does not perform any interactions.
Verify steps must never contain actions. They only observe the current page state. If your verification requires an interaction first (like clicking or scrolling), split it into two steps.

​
Separate Actions from Verifications

Wrong

Verify that when you click on the button it changes color to greenThe verify agent cannot click — this will fail.

Correct

Step 1: Click on the buttonStep 2: Verify that the button is greenAction and verification are separate steps.

​
Be Assertive and Clear

Write definitive assertions. Avoid ambiguous or conditional phrasing.

Wrong

Verify if the delivery details section is there or notCheck whether the checkout button appears on the pageWords like “if” and “whether” create ambiguity — the agent doesn’t know what outcome to expect.

Correct

Verify that the delivery details section is presentVerify that the checkout button is visibleClear and assertive — the agent knows the expected state.

​
Multiple Assertions

You can perform multiple assertions in a single verify step when checking related things on the same page state. 
Verify that the product name is "Running Shoes", the price is displayed,
and the "Add to Cart" button is visible

​
Avoid Asserting Ephemeral Content

Do not verify elements that appear and disappear quickly, such as toast notifications or loading spinners. These are unreliable because the agent may capture the page state after the element has already disappeared.

​
Writing Extract Steps

Extract steps capture visible data from the page and save it as a variable for use in later steps.

​
Ensure the Browser is in the Right State

Before extracting, make sure the page is showing the content you want to capture. If the data is only visible after scrolling, clicking, or expanding a section, perform those actions before the extract step. 
Step 1: Click on the order details dropdown
Step 2: Extract the order number as "order_id"
The agent cannot extract content that is not visible to a human user. This includes:
  • Data hidden in the HTML source or JavaScript variables
  • Content below the fold that has not been scrolled into view
  • Values that only appear after an interaction (clicking, hovering) that has not been performed yet

​
Multiple Extractions in a Single Step

You can extract up to 5 variables in a single extract step. This is recommended as it speeds up your tests. For more details, see the full Extract step reference.

​
Browser Interactions

The action agent cannot interact with the browser directly — it cannot open new tabs, switch between tabs, or look at other tabs that are open in the session. For these operations, use dedicated Browser Action steps.

Open New Tab

Open a URL in a new tab while keeping the current page

Redirect

Navigate the current tab to a different URL

Refresh

Reload the current page

​
API Requests with JavaScript

For scenarios that require API calls — such as seeding test data, resetting state, or verifying backend responses — use a JavaScript step with a fetch request. 
const response = await fetch("https://api.example.com/orders/12345", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  }
});
const data = await response.json();
return data;
Use JavaScript steps as a fallback when standard action steps or browser action steps cannot achieve what you need. For most interactions, plain-language action steps are more reliable and easier to maintain.

​
Best Practices

Each test should verify a single user flow or feature. Short tests are easier to debug when they fail and faster to re-run. If a test is getting long, consider splitting it into smaller, independent tests.
If your application displays popups, cookie banners, or modals on load, dismiss them in the first step of your test to ensure a clean starting state.
Close all pop-ups and modals
Add verify steps after critical actions to catch issues early. This also establishes checkpoints that make failures easier to diagnose.
Only extract data you will reference in subsequent steps. Unnecessary extractions slow down tests and add maintenance overhead.
When standard action, verify, or browser action steps cannot handle a scenario, use JavaScript. But prefer plain-language steps when possible — they are easier to read and maintain.

​
Quick Reference

Copy-and-paste templates for common web testing flows. 
Close all pop-ups and modals
Click the search field at the top right of the page
In the search field, enter "Running Shoes"
Verify that search results are displayed
Click the first product in the results
Verify that the product detail page is displayed

​
Form Submission

Close all pop-ups and modals
Enter "John" in the First Name field, "Doe" in the Last Name field, and "john@example.com" in the Email field
Select "United States" from the Country dropdown
Click the Submit button
Verify that the confirmation message is displayed

​
Add to Cart and Checkout

Close all pop-ups and modals
Click the first product on the page
Verify that the product detail page is displayed
Click the "Add to Cart" button
Verify that the cart icon shows 1 item
Click the cart icon in the top right
Verify that the cart page displays the correct product
Click "Proceed to Checkout"
Verify that the checkout page is displayed

​
Next Steps