Test Steps Editor
A comprehensive reference for the ContextQA step editor, covering all step types, field options, variable syntax, AI verification steps, and conditional and loop logic.
Quick answer
A comprehensive reference for the ContextQA step editor, covering all step types, field options, variable syntax, AI verification steps, and conditional and loop logic. Use this page to understand when the capability applies, complete its user-facing workflow, and verify the expected result.
What this page covers
The test steps editor is where you build, review, and refine the sequence of actions and assertions that make up a test case. Each step represents one atomic instruction — a click, a typed value, a navigation, an API call, or a verification. The editor supports multiple step types, giving you precise control over complex flows that include conditional logic, data iteration, API interactions, database verification, custom code, document generation, and AI-powered assertions.
Prerequisites
You have created or opened a test case.
You understand the difference between action steps and verification steps (see Core Concepts).
Opening the Test Case Details Screen
From the Test Cases list, click on a test case name to open it. The test case details screen has three main areas:
Header bar — Displays the test case name (click the edit icon to rename inline), status badge, priority badge, and action buttons (Record, Run, and a More menu with options like Debug, Duplicate, Delete, and Generate API test case). Warning badges appear if test data or prerequisites are missing.
Main content area — Contains a collapsible Prerequisites section at the top, followed by a tab bar with Test Steps and Relationships tabs. The Test Steps tab is selected by default.
Side panel (collapsible) — A right-side panel with three icon tabs:
Test Case — View and edit the description, metadata, labels, status, and AI settings (Default AI Action, AI Smartness level).
Variables — Manage local key-value parameters for the test case. Add, edit, delete, and bulk-delete variables directly from this panel.
Run History — View past execution results for this test case.
Adding steps
Click Add Step at the bottom of the step list. A Create a New Step modal opens with a category sidebar on the left (see Step builder categories below). You can also add a step at the first position using the + icon above the step list, or insert a step between two existing steps using the inline add action.
Reordering steps
Click the Reorder button in the tab bar to enter reorder mode. Drag steps using the handles to rearrange them, then click Done to save or Cancel to discard changes.
Note: Step group steps cannot be reordered from within the parent test case. Open the step group to reorder its internal steps.
Bulk step actions
Select multiple steps using the checkboxes to reveal a floating toolbar at the bottom of the screen with these actions:
Group
Wrap the selected steps into a new step group
Loop
Wrap the selected steps inside a new loop
Condition
Wrap the selected steps inside a new conditional branch
Duplicate
Copy the selected steps
Skip
Mark the selected steps as skipped so they do not run during execution
Unskip
Restore the selected skipped steps so they run again
Delete
Remove the selected steps
Skip appears when at least one selected step still runs, and Unskip appears when at least one selected step is already skipped. Both actions update all selected steps in a single request.
When you select a container step such as a loop or condition, its nested steps are selected with it and follow the same skip or unskip action. A step that sits under a skipped parent inherits its parent's state: if you do not include that parent in the selection, the step remains unchanged.
After a bulk action completes successfully, ContextQA clears the selected steps and dismisses the floating toolbar. This makes it clear that the grouping, loop, condition, duplication, skip, or delete operation has finished. If validation prevents an action from completing, review the message before changing the selection.
Relationships tab
The Relationships tab shows two sub-views:
Test Plans — Lists all test plans that include this test case.
Used as Prerequisite in — Lists test cases that depend on this test case as a prerequisite, with an option to replace it.
Step Builder Categories
When you click Add Step, the step builder modal opens with nine categories in the left sidebar. Select a category to see its builder form on the right.
Actions
Standard browser actions — click, type, navigate, select, scroll, hover, upload. The default category.
Loops
Create For Loop or While Loop steps to repeat a set of inner steps.
Conditions
Create If / Else If / Else conditional branches based on variable comparisons.
Database
Run database verification queries against a connected database.
Api
Make REST API calls (GET, POST, PUT, PATCH, DELETE) and store responses in variables. Uses a three-step wizard: (1) configure the request, (2) store the response in a variable, (3) verify the response.
Ai Agent
Write a plain-English instruction for the AI execution engine to interpret and perform.
Custom Code
Execute custom JavaScript code within the test flow.
Document
Generate TXT or CSV documents with configurable delimiters, templates, and key-value data mappings.
Step Group
Insert a reusable step group by searching and selecting from available groups in the workspace.
Edit in Depth
Right-click or use the step menu on any existing step and select Edit in Depth to open a full-screen editor. This modal provides access to the step's template selector, template variable fields, and advanced settings — useful for fine-tuning steps that require precise configuration beyond the inline editor.
Step Types
The following sections describe each step type in detail. These correspond to the categories available in the step builder modal.
AI Agent Step (Default)
The AI Agent step is the default step type and the most commonly used. You write a plain-English instruction and the AI execution engine interprets it and performs the corresponding browser action at runtime.
When to use: Any browser interaction — clicking, typing, selecting, hovering, scrolling, navigating — that can be described in a sentence.
Action field examples:
Tips:
Use the exact text that appears on the element in the UI (button labels, field placeholders, dropdown option text).
For fields identified by placeholder or label text, reference that text: "Type hello in the field labelled Search products".
For elements with no visible text, describe their visual appearance or position: "Click the blue Download icon next to the first row".
Navigate
The Navigate step directs the browser to a specific URL. Unlike the AI Agent step, the Navigate step uses the browser's direct URL navigation rather than simulating a user click on a link.
When to use: When you need to jump to a specific URL directly — a deep link to a page that requires direct URL access, or an absolute URL that includes query parameters.
Fields:
URL — the destination URL. Supports environment variable substitution:
${ENV.BASE_URL}/settings/billing.
Example:
REST API Call
The REST API Call step makes an HTTP request from within the test, independent of the browser. The response can be stored in a variable and used in subsequent steps.
When to use: Setting up test data before the UI test (e.g., creating a user via API before testing the UI that displays that user), tearing down test data after a test, or verifying backend state that is not visible in the UI.
The step builder uses a three-step wizard for API steps:
Step 1 — Configure the request:
Method
GET, POST, PUT, PATCH, DELETE
URL
The full endpoint URL. Supports variables: ${ENV.BASE_URL}/api/users
Headers
Key-value pairs. Use ${ENV.API_KEY} for authorization tokens
Authorization
No Auth, Bearer Token, or OAuth 2.0
Request Body
Raw JSON, form-urlencoded, or form-data. Supports variables
Parameters
Query parameters as key-value pairs
Environment
Select an environment to use its base URL
Step 2 — Store the response:
Store response in variable
Name of the variable to store the response object
Step 3 — Verify the response (optional):
JSON path
Path to a specific field in the response body for verification
Comparison
Comparison operator (equals, contains, etc.)
Data type
Expected data type of the response field
Expected value
The value to compare against
Expected status code
If set, the step fails if the response status does not match
Using API response data in later steps:
If you set "Store response in variable" to loginResponse, subsequent steps can reference:
${loginResponse.status}— HTTP status code${loginResponse.body.token}— a field from the JSON response body${loginResponse.body.user.id}— nested JSON path access${loginResponse.headers.content-type}— a response header value
Example flow:
Interactive demo: conditions and loops
Use this detailed walkthrough to see how conditional branches, For Loops, and While Loops model data-dependent or repeated behavior inside one test. The surrounding reference below explains the fields and execution behavior for each control-flow step.
What to notice
If, Else If, and Else branches make alternate application states explicit.
For Loops repeat a known number of actions, while While Loops repeat only while a condition remains true.
Child steps remain visible in the editor, making review and failure diagnosis easier than duplicated test cases.
Conditional (If / Else If / Else)
The Conditional step creates branching logic in the test execution. You can chain multiple conditions together: an If branch, one or more Else If branches, and an optional Else branch. The test engine evaluates conditions from top to bottom and executes the steps inside the first branch whose condition is true. If no condition matches, the Else branch runs (when defined).
When to use: When the test must handle different application states — for example, a feature flag that changes which UI is shown, a user role that determines which dashboard loads, or a form field whose value depends on test data.
Fields:
Condition — a variable comparison expression. Each If or Else If branch has its own condition:
${localVar} == "expected value"${apiResponse.body.status} == "active"${ENV.FEATURE_FLAG} == "true"
If-true steps — the steps to execute when the If condition is met.
Else If condition and steps — additional branches, each with its own condition and steps. You can add as many Else If branches as you need.
Else steps — optional final branch that executes when no preceding condition is true.
Creating a conditional step:
Click Add Step and select the Conditions category in the step builder.
Define the If condition and add the steps for the If-true branch.
To add an Else If branch, hover over the If step in the step list and select Else If from the step menu. Define the new condition and its steps.
Repeat step 3 for additional Else If branches.
To add an Else branch, hover over the last Else If step and select Else.
Drag steps into the appropriate branch containers using reorder mode if needed.
Tip: You can also create a conditional from existing steps. Select multiple steps using the checkboxes, then click Condition in the floating toolbar to wrap them inside a new If branch.
Simple example (If / Else):
Multi-branch example (If / Else If / Else):
How evaluation works:
The engine evaluates each condition from top to bottom.
It stops at the first branch where the condition is true and executes those steps.
All remaining branches are skipped.
If no condition matches and an Else branch exists, the Else steps run.
After the conditional block completes, execution continues with the next step in the test case.
For Loop
The For Loop step repeats a set of inner steps a fixed number of times or once per item in a data set.
When to use: When you need to add 5 items to a cart, dismiss a recurring modal, iterate over rows in a table, or repeat a form submission multiple times.
Modes:
Count-based: Repeat N times.
Data-based: Iterate over a list variable. If ${productList} contains ["Widget A", "Widget B", "Widget C"], the loop runs three times with ${item} set to each value in turn:
While Loop
The While Loop step repeats a set of inner steps until a specified condition becomes false (or until a maximum iteration count is reached, as a safety guard).
When to use: When you need to wait for an asynchronous process to complete — polling for a background job to finish, waiting for a status field to change, retrying until a dynamic element appears.
Fields:
Condition — the loop continues while this condition is true:
${jobStatus} != "complete"Max iterations — safety limit to prevent infinite loops (default: 25, maximum: 50). The loop fails at this step once it reaches this many iterations if the condition is still true. You can set this cap when you create the while-loop step or when you edit it in the Edit-in-depth modal.
Inner steps — the steps to execute on each iteration
The editor limits the child-step choices inside a While Loop to supported operations. If For Loop or Step Group is not offered while adding an inner step, create a flatter flow or move the reusable sequence outside the While Loop instead of trying to force an unsupported nested structure.
Example:
Step Group
The Step Group step inserts a named, reusable step group at a specific point in the test case. At execution time, the step group expands and its individual steps run in sequence as if they were inline steps.
When to use: Any repeated setup or teardown pattern — login sequences, navigation to a module, closing persistent UI elements (cookie banners, chat widgets), completing a checkout flow that precedes the actual test assertion.
Fields:
Step Group — search and select from the available step groups in the workspace.
Behavior:
Changes to the step group are reflected in all test cases that use it without requiring the test cases to be re-saved.
Step group steps appear individually in the execution report, not as a collapsed entry — each step shows its own pass/fail status and screenshot.
AI Verification
The AI Verification step uses a vision-language AI model to evaluate a natural language condition against the current browser state. It is the most flexible assertion type, handling dynamic, non-deterministic content that cannot be verified with exact string matching.
When to use:
Verifying that a dynamically generated value (order ID, timestamp, random token) exists and is plausible.
Confirming visual states ("the chart rendered successfully", "the map shows a marker in London").
Checking relative conditions ("the error message is displayed below the Password field").
Any condition that requires understanding context rather than matching a literal string.
Action field examples:
How it differs from a standard AI Agent step: A standard AI Agent step performs an action. An AI Verification step produces a pass/fail result based on evaluating the current screenshot against the stated condition. Use the AI Verification type explicitly for assertion steps so the execution report correctly categorizes them as verifications rather than actions.
Verification data sources
When a verification includes an expected value, choose its source in the test-data value picker:
Plain Text
Verify a fixed heading or message.
Test Data Profile
Verify the expected outcome for the active data row.
Runtime
Verify an ID or value captured earlier in this execution.
Environment Variable
Verify an environment-specific non-secret label or URL.
Global Data
Verify an approved workspace-wide constant.
Random
Generate a value for an earlier action; capture it before using it as an expected value later.
Build mixed values by typing the fixed portion and inserting the dynamic portion with the picker. Do not paste environment secrets into the natural-language verification prompt. For exact financial, schema, or contract checks, prefer deterministic REST API or Custom Code validation; AI Verification is best for contextual or visual conditions.
Step Editor Fields Reference
Every step, regardless of type, has the following common configuration fields:
Step Name / Description
The plain-English instruction or assertion. This is what appears in the step list and in the execution report.
Step Type
Dropdown selecting the step type (AI Agent, Navigate, REST API Call, Conditional, For Loop, While Loop, Step Group, or AI Verification).
Wait Condition
Optional condition that must be satisfied before this step executes: Wait for element visible, Wait for URL to contain, Wait for network idle, Wait N seconds.
Screenshot Capture
Controls when a screenshot is captured: Always (default), On Failure Only, Never.
Mark as Optional
If enabled, a failure on this step does not fail the overall test case. Useful for non-critical UI enhancements or known-flaky elements.
Timeout
Maximum time (in seconds) to wait for the step action to complete before marking it as failed. Default: 30 seconds.
Variables in Steps
ContextQA supports local, global, environment, and Test Data Profile values. Their stored token formats differ, so insert them with the value-source picker rather than assuming one universal ${variableName} syntax.
Local Variables
Scoped to the test case. Defined in the Variables tab of the side panel or set dynamically by REST API Call steps.
Setting a local variable dynamically: In a REST API Call step, use "Store response in variable" to save the response. Individual fields are accessed via dot notation on the stored object.
Global Variables
Workspace-scoped. Available to every test case in the workspace. Defined in Environment & Data → Global Data.
Global variables are useful for values that are shared across many test cases but are not environment-specific — a default admin account email, a test project name, a default search term.
Environment Parameters
Values from the currently selected environment. Insert them through the data picker; for example, baseURL appears as *|baseURL|*.
Environment parameters allow the same test step to work against staging, QA, and production without modification. Select the environment on the test case or in the plan configuration that executes it.
Test Data Profile Variables
When a test case has a test data profile attached, each column in the profile becomes a variable available in the test steps.
Map each relevant input or verification step to a profile column through the Parameter picker. When a Test Data Profile loop is configured, the selected steps repeat across the chosen row range.
Tips & Best Practices
Keep AI Agent step descriptions action-oriented. Start with a verb: "Click", "Type", "Select", "Scroll", "Verify", "Navigate". The AI execution engine recognizes these action verbs and dispatches them to the correct browser interaction handler.
Use AI Verification steps for all assertions. Even when an assertion could theoretically be expressed as a standard AI Agent step ("verify the heading says Dashboard"), using the explicit AI Verification type ensures the step is tracked as an assertion in the execution report and counted in pass/fail statistics correctly.
Set timeouts explicitly for slow operations. If your application has pages that take more than 30 seconds to load (reports, data exports, dashboard renders), increase the timeout on the relevant steps to avoid premature failures.
Mark setup steps as Optional when appropriate. Cookie banner dismissal steps, onboarding tour dismissal, and similar incidental actions that may or may not appear can be marked Optional so they don't fail the test if the UI state doesn't require them.
Use For Loop for repetitive data entry. When a test needs to add multiple rows to a table or submit a form multiple times with the same structure, use For Loop with a data set variable rather than duplicating steps.
Troubleshooting
An AI Agent step is clicking the wrong element Refine the step description to be more specific. Add context about the element's location ("in the header", "in the confirmation dialog"), its label ("the button labelled Submit Order, not the Cancel button"), or its visual appearance ("the blue primary action button").
A REST API Call step fails with a 401 Unauthorized response Verify that the Authorization header is correctly formatted and that the token variable it references has been set by an earlier step. Check the network log in the execution report to see the exact request headers that were sent.
A Conditional step is not taking the expected branch Add a temporary AI Agent step before the conditional that logs the value of the condition variable: "Verify the page shows the value of ${myVar}". Run the test and check the screenshot to see what value the variable actually holds.
Step Group steps are not appearing individually in the report This behavior was changed in a recent release. If you are on an older workspace version, the step group may appear as a collapsed entry. Contact support to upgrade your workspace to the current execution engine.
While Loop is hitting the max iteration limit The default limit is 25 iterations. If your polling loop needs more iterations, increase the Max iterations field, up to the maximum of 50. Also consider increasing the wait time between iterations to give the background process more time to complete before each poll.
Related Pages
Last updated
Was this helpful?