> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spurtest.com/llms.txt
> Use this file to discover all available pages before exploring further.
> ## 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.
# Web Prompting Guide
> Write clear, reliable test instructions for web applications that produce consistent results.
## 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 this | Write 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 value | Type "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 appear | Click 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.
### Combine Related Form Actions
You can combine multiple form-filling actions into a single step when they are on the same form. This speeds up test execution.
```text theme={null}
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.
```text theme={null}
Scroll down to the "Reviews" section
```
```text theme={null}
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](/authoring-tests/test-side-peek/step-types/actions/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
**Verify that when you click on the button it changes color to green**
The verify agent cannot click — this will fail.
**Step 1:** Click on the button
**Step 2:** Verify that the button is green
Action and verification are separate steps.
### Be Assertive and Clear
Write definitive assertions. Avoid ambiguous or conditional phrasing.
Verify **if** the delivery details section is there or not
Check **whether** the checkout button appears on the page
Words like **"if"** and **"whether"** create ambiguity — the agent doesn't know what outcome to expect.
Verify **that** the delivery details section is present
Verify **that** the checkout button is visible
Clear 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.
```text theme={null}
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.
```text theme={null}
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](/authoring-tests/test-side-peek/step-types/extract).
## 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 a URL in a new tab while keeping the current page
Navigate the current tab to a different URL
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](/authoring-tests/test-side-peek/step-types/javascript) with a fetch request.
```javascript theme={null}
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.
```text theme={null}
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.
### Dismiss Popups and Search
```text theme={null}
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
```text theme={null}
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
```text theme={null}
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
* Read the [Mobile Prompting Guide](/getting-started/mobile-prompting) for mobile-specific instructions
* Browse the [Prompt Library](/getting-started/prompt-library) for ready-to-use prompt patterns
* Review [Common Pitfalls](/getting-started/common-pitfalls) for detailed examples of mistakes to avoid