Write effective steps and Expected Outcomes

Testmode turns each step into a few browser operations: an action on one element, a wait for something to appear, a check that something is true. The clearer a step says which element and which value, the better those operations match what you meant. This page covers the wording that works; for the mechanics, see How Testmode runs a test.

Each action in a step becomes one operation on one element. Write steps the way you’d instruct a colleague at the keyboard: name the element, quote the value, say the action.

Several actions in one step are fine; Testmode splits them in order. Keep one goal per step, so a failure points at it: “Failed at step 3” tells you more when step 3 does one thing.

Put buttons, fields, options, headings and messages in quotation marks, exactly as the page shows them, capitals and punctuation included. Testmode finds elements by the words you give it, so exact wording removes guesswork.

Vague steps are the most common reason a test does something unexpected: “submit the form” may compile to a click on the wrong button. The editor flags a step that may be too vague to run reliably, with an example of what to say instead. When a label changes on your site, update the step; the reworded step is compiled again on its next run.

When a page loads content after an action, say what to wait for. A Wait for checks the page until it appears, for up to 20 seconds:

Wait until the heading "Searched for: hammer" appears.
Wait until the product list shows "Slip Joint Pliers".

A fixed wait (“Wait 5 seconds”) works too, but it is slower when the page is quick and fails when it is slow. Use it only for animations that have nothing to wait for.

A step that only describes what to look at becomes a check that must be true at that moment. A false check fails the test right there:

3. Verify the cart badge shows "1".
4. Open the cart from the cart icon in the navigation menu.

Use checks for things that must hold before the test goes on. Put the final result in the Expected Outcome.

A check can note a figure for later: the Expected Outcome is told what the checks before it found on the page, so it can compare with them.

2. Verify the cart badge shows a number.
3. Click "Add to cart".

Expected Outcome: The cart badge shows one more than the number verified in step 2.

“Reload the page.” reloads the browser. Use it to check that a change was saved, not only shown:

3. In "Sort", choose "Price (Low - High)".
4. Reload the page.
5. Verify "Sort" still shows "Price (Low - High)".

Use Start path rather than a navigation step. The browser opens that page before step 1.

Write a path, never a full URL: it is added to the environment’s URL, which is what lets the same test run on staging and production. For pages whose address changes, such as a product page with an id in its URL, start on a stable page and search or click your way there.

Attach a Login credential instead of writing login steps. Testmode signs in before step 1, so the test starts logged in.

• Don’t write “Log in as Jane” or type a password in a step. A step that looks for a login form fails, because the form isn’t there. When a step holds login details, the editor offers Move to a saved login.
• Start on a page that shows the signed-in state, such as an account page.
• Don’t sign out in a test that shares a credential with other tests: it ends their login too.

1. Look at the page heading and the navigation menu. Do not click "Sign out".

Expected Outcome: The page heading reads "My account", and the navigation menu shows the customer's name instead of "Sign in".

“Do not click” phrases are read as context, not as actions. See Credentials and automatic login.

After the last step, Testmode reads the page and decides whether your Expected Outcome holds. Describe what is on the screen when the test has passed: a heading, a message, the items in a list, a value in a field.

• Say what must not happen when it matters. A validation test is stronger when it also says the success message doesn’t appear.
• Every part must hold. Testmode splits the outcome into its parts and finds each one on the page, quoting what it saw. One part it can’t find fails the test, so leave out what you don’t need.
• Describe looks in words, and only where the page’s text and structure show them: “the product photo is shown, not a broken image”. Testmode reads the page; it is not a pixel-by-pixel visual comparison.
• Things outside the page can’t be checked: an email arriving, a database row, a webhook.

Variables are for text a test types or checks: {{Search Term}}, {{Support Message}}. Don’t use one as the name of something to click or choose, such as Click the {{Product}} link: Testmode picks the element from the step’s own words and can’t see the value at that moment. Write such names out. See Variables.

A variable name must match exactly, capitals and spaces included; add variables with Insert variable rather than typing them. A misspelled name such as {{Suport Message}} is typed as literal text, braces included.

Tests in a run execute at the same time, each in its own fresh browser, in no guaranteed order.

• Don’t rely on another test. A product one test adds to the cart is not in another test’s browser. Each test sets up what it needs.
• Split long journeys. Several short test cases, each with one clear outcome, point to the one thing that broke, and each finishes well inside its time limit.
• Name tests after what they check, so a failure in a report email already says what broke.

When a click opens a confirmation dialog, such as “Delete” beside “Cancel”, Testmode clicks its confirming button, so “Click “Delete” on the order.” deletes the order. To test the dialog itself, make the next step about it: “Click “Cancel” in the dialog.” Then it is left open for that step.

Some sites need a second click to finish an action. On the Toolshop’s payment step, the button first reads “Check payment”; once the payment is checked, it reads “Confirm” and places the order. Write each click as its own step, with the condition that triggers the second:

6. On the "Payment" step, choose "Cash on Delivery" under "Payment Method" and click "Check payment".
7. When a message about the payment appears under the form, click "Confirm".

Expected Outcome: The page shows "Thanks for your order! Your invoice number is" followed by an invoice number.

• Leave your site and come back. Flows that pass through another domain, such as “Sign in with Google” or an external payment page, are not reliable.
• Read email or SMS, so they can’t follow a confirmation link or type a one-time code.
• Solve a CAPTCHA. Turn it off on the environment you test.

See What Testmode can and cannot test.

Name: Contact form test
1. Go to the contact page.
2. Fill in the form with a short message.
3. Submit it.

Expected Outcome: Validation works.

Name: Contact form requires a 50-character message
1. Fill "First name" with "Maren", "Last name" with "Veld" and "Email address" with "maren.veld@example.com".
2. In "Subject", choose {{Contact Subject}}.
3. Type {{Short Message}} into "Message" and click "Send".

Expected Outcome: The form shows "Message must be minimal 50 characters" and the text "Thanks for your message! We will contact you shortly." does not appear.

What changed: the name says what is checked, Start path replaces the navigation step, every field and button is quoted, the values come from variables, and the outcome names the exact message and what must not appear.

Name: Cart
1. Add some pliers to the cart and check the cart.

Expected Outcome: It worked.

Name: Add a product to the cart
1. Type "Slip Joint Pliers" into the "Search" field and click "Search".
2. Open the product "Slip Joint Pliers".
3. Click "Add to cart".
4. Open the cart from the cart icon in the navigation menu.

Expected Outcome: The message "Product added to shopping cart." appears after adding, and the cart lists "Slip Joint Pliers".

What changed: one crowded step became four, each naming its element; “some pliers” became one exact product; and the outcome says what the page shows.