End-to-End Testing: A Practical Guide
End-to-end tests cover the critical user journeys. Learn the selectors, the flakiness fixes, and how to keep the suite small and reliable.
By Velloreth
What an end-to-end test is
An end-to-end test drives the whole system.
test('a user can place an order', async ({ page }) => {
await page.goto('/products');
await page.getByRole('button', { name: 'Add to cart' }).click();
await page.getByRole('link', { name: 'Checkout' }).click();
await page.getByLabel('Card number').fill('4242424242424242');
await page.getByRole('button', { name: 'Pay' }).click();
await expect(page.getByText('Order confirmed')).toBeVisible();
});
Every component is real: the browser, the front end, the API, the database.
It catches a bug no other test can, such as a broken form, a missing route, or a misconfigured CORS header.
Keep the number small
Cover the critical journeys:
- Sign up
- Log in
- The main action the product exists for
- The payment flow
- A password reset
A handful is enough. More than that becomes slow and flaky, and the marginal value drops.
The pyramid still applies. The unit and integration tests cover the detail; the end-to-end tests cover the journey.
Selectors
A stable selector is the difference between a reliable suite and a flaky one.
Prefer a role-based selector:
page.getByRole('button', { name: 'Submit' });
It matches what a user perceives, and it survives a style refactor.
A test id is the fallback:
page.getByTestId('submit-button');
Avoid a CSS class:
page.locator('.btn-primary.mt-4'); // breaks on a style change
Avoid a text selector for a copy that changes:
page.locator('text=Click here to submit'); // breaks on a copy edit
The rule: select by role, then by test id, and never by a style class.
Waiting
Never use a fixed sleep.
await page.waitForTimeout(2000); // slow and flaky
Wait for a condition:
await expect(page.getByText('Order confirmed')).toBeVisible();
The assertion retries until it passes or times out, so it returns as soon as the condition is true.
Wait for a network response when the UI depends on it:
await page.waitForResponse((r) => r.url().includes('/api/orders') && r.ok());
The auto-waiting assertion is the key feature of a modern runner. Use it rather than a sleep.
Independence
A test must not depend on another.
The problem: a test that logs in and then places an order depends on the login test having run.
The fix: each test sets up its own state, through the API rather than the UI where possible.
test.beforeEach(async ({ request }) => {
await request.post('/api/test/reset');
await request.post('/api/test/seed', { data: { user: 'alice' } });
});
Seeding through the API is faster than through the UI, and it keeps the test focused on the journey it is testing.
Authentication
Logging in through the UI in every test is slow.
The fix: log in once, save the storage state, and reuse it.
// auth.setup.js
await page.goto('/login');
await page.getByLabel('Email').fill('alice@example.com');
await page.getByLabel('Password').fill('password');
await page.getByRole('button', { name: 'Log in' }).click();
await page.context().storageState({ path: 'auth.json' });
// The test reuses the saved state
test.use({ storageState: 'auth.json' });
This saves a login per test, which is often the largest single speed-up.
Page objects
A page object wraps a page’s selectors and actions.
class CheckoutPage {
constructor(page) {
this.page = page;
this.cardNumber = page.getByLabel('Card number');
this.payButton = page.getByRole('button', { name: 'Pay' });
}
async pay(card) {
await this.cardNumber.fill(card);
await this.payButton.click();
}
}
The test reads as a sequence of user actions:
await checkout.pay('4242424242424242');
The benefit: a selector change is fixed in one place, and the test is readable.
The risk: a page object that grows into a second implementation of the page. Keep it thin.
Debugging a failure
A screenshot on failure is the first thing to add.
test.afterEach(async ({ page }, testInfo) => {
if (testInfo.status !== 'passed') {
await page.screenshot({ path: `failure-${testInfo.title}.png` });
}
});
A trace records the DOM, the network, and the console, and it can be replayed.
test.use({ trace: 'on-first-retry' });
The trace viewer is the fastest way to diagnose a flaky failure, because it shows the state at each step.
Run the test headed to watch it, and use --debug to step through.
Flakiness
A flaky test is worse than no test, because it trains the team to ignore a red build.
The causes:
- A fixed sleep
- A selector that matches several elements
- A shared state between tests
- A dependency on an external service
- An animation that delays a click
The fixes:
- Wait for a condition
- Use a specific selector
- Reset the state per test
- Stub the external service
- Disable the animation in the test environment
Quarantine a flaky test rather than ignoring it: move it to a separate suite, and fix it. A test that is ignored is a test that will fail in production.
Keeping the suite healthy
An end-to-end suite degrades over time unless it is maintained, and the degradation is usually gradual. A test that was reliable becomes flaky as the application grows, a selector that was specific becomes ambiguous, and a journey that was critical becomes obsolete. The practice that keeps the suite healthy is to treat a flaky test as a bug rather than an annoyance: quarantine it, find the cause, and fix it, because a test that is ignored is a test that will fail in production. The second practice is to review the suite periodically and remove a test for a journey that no longer matters, because a suite that only grows becomes slow and the team stops running it. The third is to keep the critical journeys covered and resist the temptation to add an end-to-end test for every new feature, because the unit and integration tests are the right place for the detail.
Practical guidance
- Cover the critical journeys, and keep the number small.
- Select by role, then by test id.
- Wait for a condition, never a sleep.
- Reset the state per test.
- Reuse the auth state.
- Use a page object for a repeated flow.
- Capture a screenshot and a trace on failure.
- Quarantine a flaky test and fix it.
- Run the critical ones on every pull request.
For the related guides, see integration-vs-unit-tests and why-your-tests-are-slow. For the broader context, unit-testing-basics and ci-cd-pipeline-basics.
Quotable summary
An end-to-end test drives the whole system, so it catches a bug no other test can, such as a broken form or a missing route, and the number should stay small with the critical user journeys covered. A stable selector is the difference between a reliable suite and a flaky one, so select by role and then by test id, and never by a style class that changes with a refactor. Wait for a condition rather than a fixed sleep, because the assertion retries until it passes and returns as soon as the condition is true. A flaky end-to-end test is worse than no test, because it trains the team to ignore a red build, so quarantine it and fix it rather than ignoring it.