# What is a user journey test?

A user journey test follows one real task a user performs, e.g. signing up, across every screen and service it touches, and checks each step.

Last updated September 29, 2026, 9 min read

## Learning objectives

After reading this article you will be able to:

-   Define a user journey test
-   Identify what a journey test checks beyond the screen
-   Explain how to choose which journeys to test

## Related content

-   [What is software testing?](https://specstory.com/learning/testing/software-testing)
-   [What is end-to-end testing?](https://specstory.com/learning/testing/end-to-end-testing)
-   [What is acceptance testing (UAT)?](https://specstory.com/learning/testing/acceptance-testing)
-   [What is exploratory testing, and can an AI agent do it?](https://specstory.com/learning/testing/exploratory-testing)

## What is a user journey test?

A user journey test is a test that follows one user task from start to finish through the running software and checks each step. It is also called a user flow test. The task is one a real person does to reach a goal, e.g. placing an order, and the test passes only when that goal is reached.

Google's Site Reliability Engineering (SRE) workbook [defines critical user journeys](https://sre.google/workbook/implementing-slos/) as sequences of tasks that form a core part of a user's experience of a service. In its online shop example, searching for a product, adding it to a cart, and completing a purchase are three separate journeys.

In [software testing](https://specstory.com/learning/testing/software-testing), most user journey tests run as [end-to-end tests](https://specstory.com/learning/testing/end-to-end-testing), and many also serve as [acceptance tests](https://specstory.com/learning/testing/acceptance-testing). A journey test can catch a task that breaks between parts while each part passes its own tests.

The term differs from a customer journey map, which user experience designers use to chart what a customer does and feels.

## How does a user journey test work?

A user journey test works in these steps:

1.  A tester or developer who knows the product writes the task as steps with expected results. A feature request often changes an existing journey, and its [acceptance criteria](https://specstory.com/learning/glossary#acceptance-criteria) supply the changed results.
2.  The test loads known starting data, e.g. a seeded account with an empty cart, as part of [test data management](https://specstory.com/learning/glossary#test-data-management).
3.  The test drives the software through the user's surface, often a [headless browser](https://specstory.com/learning/cli-and-web/headless-browser).
4.  After each step, the test checks what the user would see.
5.  The test also checks state that the page does not show, e.g. the stored order.
6.  If a step fails, the test stops and reports the step, its inputs, and the result, which become the [reproduction steps](https://specstory.com/learning/debugging/reproduction-steps) for the bug.

Diagram: What a user journey test checks

Each step has a check on the page. The checks below the steps catch a task that failed while its pages looked right.

A page can look right while the task has failed, so a journey test also checks what the page does not show:

-   **State between steps.** The cart and the login session carry over between pages.
-   **Stored data.** The saved record matches what the user entered, e.g. the delivery address on the order.
-   **Messages sent.** The task sends one confirmation email, not two or none.
-   **Hidden errors.** No failed request or console error sits behind a page that looks fine.

## What is an example of a user journey test?

Here is an illustrative example. Acme Co. sells furniture online. A developer asks a [coding agent](https://specstory.com/learning/ai-coding/coding-agent) to "Let customers edit their delivery address during checkout."

Before the agent starts, the developer updates Acme's checkout journey test from the request. The agent changes the checkout code, and the tests it wrote pass. The journey test then runs six steps:

1.  The test signs in as a seeded customer whose saved address is 4 Oak Road.
2.  The test adds 2 oak chairs to the cart.
3.  The test starts checkout and changes the delivery address to 12 Elm Street.
4.  The test checks the review page, which shows 12 Elm Street and a total of $240.00.
5.  The test places the order and reads the order number, `A-1042`.
6.  The test fetches order `A-1042` from the store's API and checks its address and items.

Steps 5 and 6 look like this in Playwright, where `page.request` sends the API call with the customer's session cookies:

```js
await page.getByRole("button", { name: "Place order" }).click();
const id = await page.getByTestId("order-id").textContent();
const res = await page.request.get(`https://shop.example.com/api/orders/${id}`);
const order = await res.json();
expect(order.deliveryAddress).toBe("12 Elm Street");
expect(order.items).toHaveLength(2);
```

The address check fails:

```text
Error: expect(received).toBe(expected) // Object.is equality

Expected: "12 Elm Street"
Received: "4 Oak Road"
```

The review page showed the edited address, but the stored order kept the saved one. The agent's change wrote the edit to the checkout session and never copied it to the order. A test that stopped at the review page would pass. This example is simplified. A real checkout journey would also check the payment and the confirmation email.

## How do you choose which journeys to test?

Ham Vocke's [The Practical Test Pyramid](https://martinfowler.com/articles/practical-test-pyramid.html) advises teams to find "user journeys that define the core value of your product" and automate their main steps. His shop example is one journey from search to checkout, while the SRE workbook splits that path into three. A shorter journey fails closer to its cause, and a longer one checks more handoffs. Teams often rank candidate journeys by these criteria:

-   **Money or data at stake.** A journey whose failure stops sales or loses data comes first, e.g. checkout.
-   **Frequency.** A broken task that most users repeat, e.g. signing in, affects the most sessions.
-   **First use.** A user who cannot finish signing up never reaches the rest of the product.
-   **The change.** A journey that crosses the changed code runs first, because it is more likely to break.

Each journey usually gets one test along its [happy path](https://specstory.com/learning/glossary#happy-path), the expected route with valid input. Variations, e.g. a declined card, belong in faster tests lower in the [test pyramid](https://specstory.com/learning/testing/test-pyramid). A few short journeys can also run as a [smoke test](https://specstory.com/learning/testing/smoke-testing) after each deploy.

## What changes when a coding agent writes the code?

[Martin Fowler writes](https://martinfowler.com/bliki/UserJourneyTest.html) that user journey tests are not tied to user stories, so one journey can outlast many changes. A coding agent works on one request at a time, and the tests it adds often cover only that request. In the Acme example, the agent's tests checked only the address edit.

An agent that repairs a failing journey test can also shorten it. Deleting the check on the stored order, or moving it to the review page, makes the Acme test pass. The file still reads as a checkout journey, but it no longer reaches the goal.

A practical adjustment is to end each critical journey with a goal check that a person owns, e.g. a check on the stored order. Reviewers then treat any edit that removes a step or that check as a change to the journey, not a repair.

## What are the limits of journey tests?

Journey tests have these limits:

-   **One path per journey.** A journey test follows one route, so a failure off that route, e.g. an expired session, goes unchecked.
-   **Slow and brittle.** Most runs need the whole system, and a layout change can break a step that still works.
-   **Only the journeys someone wrote.** A passing journey suite does not establish that the whole app works. [Exploratory testing](https://specstory.com/learning/testing/exploratory-testing) finds some of the paths nobody scripted.
-   **Drift from the product.** When the product changes and the test does not, the test checks a journey users no longer take. That gap is a form of [spec drift](https://specstory.com/learning/glossary#spec-drift).
-   **One user per script.** A script that signs in as one user misses a failure that only a second user meets, e.g. staff who cannot see the order. Covering both users needs a second session in the same test. Checking that one user cannot see another's data is the job of a [two-account test](https://specstory.com/learning/glossary#two-account-test).

## How is a journey test different from an end-to-end test?

Engineers often define an end-to-end test by scope, because it runs the whole system through its outside surface. A user journey test is defined by purpose, because it follows one user task to its goal. Most journey tests are end-to-end tests, and definitions of end-to-end testing that start from a business process describe both. The two differ when an end-to-end test checks a single action, e.g. that the product page loads, or when a journey test replaces the backend with stubbed responses.

## How does RunStory help with user journey tests?

A journey suite checks the tasks someone listed, and a coding agent's change can break a task that is not on the list. RunStory considers your prompts and code changes to decide what to test. It runs your software in a separate environment, tries relevant workflows, and checks the results. RunStory is in private alpha for CLIs and web apps. Your team keeps the final release decision.

[Join the RunStory alpha →](https://specstory.com/runstory#alpha)

## FAQs

### What is a critical user journey?

A critical user journey is a sequence of tasks that forms a core part of a user's experience of a service, e.g. completing a purchase. A user journey test is the check that runs one such journey and shows whether it still works.

### Are user journey tests the same as smoke tests?

User journey tests and smoke tests overlap, but they are not the same. A smoke test checks quickly that a build starts and its main paths respond. A journey test follows one task to its goal and checks each step, and a short journey can also run as a smoke check.

### Who writes user journey tests?

User journey tests are usually written by a tester or developer who knows the product and its users' tasks. When a coding agent writes the code, a person can write the journey from the request before the agent starts, so the agent does not set the expected results.

### Can a journey test cover more than one user?

A journey test can cover more than one user when a task needs two people, e.g. a customer who orders and a staff member who ships. The test opens a second session in the same run and switches between the two at each handoff.

---

Source: [What is a user journey test? | Critical journeys | SpecStory](https://specstory.com/learning/testing/user-journey-testing)