Assertions

Why it matters

A test finds only the defects its assertions look for. A checkout test that asserts only that "a total is visible" stays green when the VAT is not added, and the green run tells the team the feature works. ISTQB calls a result that misses a defect that is present a false-negative result; weak assertions produce them silently.

The opposite error is expensive too. Assertions that read the page too early, or check details nobody specified, fail when nothing is wrong: false-positive results. Each false alarm costs an investigation, and a team that sees many of them starts re-running red builds instead of reading them. Precise, retrying assertions with clear messages keep a suite trustworthy: when it fails, the message tells you whether to open a defect.

What to check: the outcome, exactly

Every assertion needs an expected result from a test oracle: the requirement, the acceptance criteria, the API documentation or the test case. Never take it from what the application shows today; copying the current output into the assertion turns an existing defect into "expected" behaviour.

A strong assertion checks the outcome the oracle describes, as precisely as the oracle fixes it. A weak assertion checks something that is also true when the feature is broken: an element exists, a value is not empty, the response is "OK". The running example in this lesson: two items worth 150.00 SAR plus 15% VAT must give a total of 172.50 SAR.

• Exact values where the requirement fixes them: toHaveText('172.50 SAR'), not toBeVisible() on the total. Money, counts, statuses and messages are compared exactly.
• Patterns only for parts that really vary: an order number such as ORD-418305 is checked with /^ORD-\d{6}$/, not with toBeTruthy() and not with the number from one run.
• Counts, not "at least one": toHaveCount(2), not a check that count() is greater than 0.
• The effect, not only the absence of an error: after the order the cart badge shows 0; if the API documentation says that creating an order returns 201 with the new order in the body, check that status and those values, not just any 2xx status.
• Absence with an anchor: "no error banner" is also true on a blank page, so assert a positive signal first, then the absence.
• Not too much: CSS classes, page structure, timestamps and generated ids make a test fail on harmless changes. Assert one behaviour per test, with as many assertions as it takes to prove it.

Try it: REST API Tester Try it: JSON Path Tester

Hard and soft assertions

A hard assertion stops the test at the first failure: expect throws, the runner records the error, and the lines after it never run. This is the default in every framework, and it is right when later steps depend on the check: if the confirmation page did not open, asserting on its total only adds noise.

A soft assertion records the failure and lets the test continue; at the end the test is still marked failed, with every failed check listed. Use it for independent facts about one result, such as the fields of one page or one response, so a single run shows every mismatch instead of one per fix-and-rerun cycle. Keep preconditions hard.

• JUnit 5 and later: assertAll(...) runs a group of assertions and reports every failure in the group; AssertJ offers SoftAssertions.
• TestNG: SoftAssert reports only when assertAll() is called at the end; forget that call and the failures are lost.
• pytest: a plain assert is hard; soft checks come from plugins.

// Hard: the precondition. If it fails, the checks below would mean nothing.
await expect(page.getByRole('heading', { name: 'Order confirmed' })).toBeVisible();

// Soft: independent facts about the same page, all reported together.
await expect.soft(page.getByTestId('order-status')).toHaveText('Paid');
await expect.soft(page.getByTestId('order-item')).toHaveCount(2);
await expect.soft(page.getByTestId('order-total')).toHaveText('172.50 SAR');

Retrying (web-first) assertions

A page changes after every action: the click returns, the request reaches the server, and only then does the text update. An assertion that reads the page once can read it too early. Retrying assertions, which the Playwright documentation calls auto-retrying or web-first assertions, take a locator instead of a value and check again until the condition is met or a timeout ends (5 seconds by default in Playwright, configurable). Cypress retries the query before .should() in the same way. Selenium has no retrying assertions: wait for the condition with WebDriverWait, then assert.

The difference is where the await sits. await expect(locator).toHaveText('Paid') hands the locator to the assertion, which keeps asking the page. expect(await locator.textContent()).toBe('Paid') reads once and compares a string that will never change, so the result depends on timing, a classic cause of flaky tests. Generic matchers such as toBe and toEqual do not retry on their own; use them for values that are already complete, such as a parsed response body. For values outside the page, expect.poll() calls a function again and again and applies the matcher to each new result.

• Retrying in Playwright: toBeVisible, toHaveText, toContainText, toHaveValue and toHaveCount on a locator; toHaveURL and toHaveTitle on a page.
• Negative checks retry too: not.toBeVisible() waits for an element to disappear, and passes at once if it never appeared, which is why it needs an anchor.
• Retrying waits for the right answer; it does not fix a wrong expectation. Raise the timeout only for a known slow step, on that one assertion. The lesson on waits and synchronization goes deeper.

// Reads once: may compare the text from before the server answered
expect(await page.getByTestId('order-status').textContent()).toBe('Paid');

// Retries until the text is "Paid" or the timeout ends (5 s by default)
await expect(page.getByTestId('order-status')).toHaveText('Paid');

// A value outside the page: poll the API until the order is paid
await expect.poll(async () => {
  const res = await request.get('/api/orders/' + orderId);
  return (await res.json()).status;
}).toBe('PAID');

Failure messages that explain themselves

When a test fails in a night run, its failure message is often the first thing anyone reads. A useful message answers three questions without opening the code: what was checked, what was expected and what was received. Matchers that compare real values give you the last two for free; a boolean throws them away. The outputs below are shortened; the exact layout depends on the runner version.

• Prefer matchers that carry the values (toHaveText, toEqual, toHaveCount) to toBe(true) and toBeTruthy().
• Add a custom message where the matcher cannot know the context: the second argument of expect in Playwright, the last argument of assertEquals in JUnit 5 and later, the text after the comma in pytest: assert total == 172.5, "order total with VAT".
• Write it as the business fact, like a bug title: "order status after card payment", not "check 3". When a test loops over data, include the case in the message.
• For objects, toEqual prints a diff of the fields that differ; toMatchObject compares only the fields you list, which keeps timestamps out of the comparison.

Weak:    expect(await status.isVisible()).toBe(true);

         Error: expect(received).toBe(expected)
         Expected: true
         Received: false

Strong:  await expect(status, 'order status after card payment').toHaveText('Paid');

         Error: order status after card payment
         Expected string: "Paid"
         Received string: "Pending"

Try it: Text Diff Try it: JSON Diff

Worked example: strengthening a checkout test

Requirement: "After payment, the confirmation page shows the order number (ORD- and six digits), the status Paid, the ordered items and the total including 15% VAT. The cart is emptied." The test cart holds two items worth 150.00 SAR, so the expected total is 172.50 SAR.

• Before, the first two checks read once and accept anything: a total of 150.00 SAR, or an order number of ORD- with no digits, stays green. After, the exact total and the number pattern are compared, with retries.
• The "Order confirmed" heading is hard: without the confirmation page nothing else means anything. The five facts from the requirement are soft, so one run reports every one that is wrong.
• The check on "Error" is gone: it passed on a blank page, and once the heading and the values are proven it adds nothing.
• The new test title states the behaviour, so the report reads like the requirement. The order time and the CSS classes are not asserted: the requirement does not mention them.

// Before: stays green as long as the page opens
test('place order', async ({ page }) => {
  const checkout = new CheckoutPage(page);
  await checkout.payWithTestCard();
  expect(await page.locator('.total').isVisible()).toBeTruthy();
  expect(await page.locator('.order-no').textContent()).toBeTruthy();
  await expect(page.getByText('Error')).not.toBeVisible();
});

// After: each assertion proves one part of the requirement
test('card payment confirms order with VAT and empties cart', async ({ page }) => {
  const checkout = new CheckoutPage(page);
  await checkout.payWithTestCard();
  await expect(page.getByRole('heading', { name: 'Order confirmed' })).toBeVisible();
  await expect.soft(page.getByTestId('order-number')).toHaveText(/^ORD-\d{6}$/);
  await expect.soft(page.getByTestId('order-status')).toHaveText('Paid');
  await expect.soft(page.getByTestId('order-item')).toHaveCount(2);
  await expect.soft(page.getByTestId('order-total'), 'total = 150.00 + 15% VAT')
    .toHaveText('172.50 SAR');
  await expect.soft(page.getByTestId('cart-count')).toHaveText('0');
});

Try it: Regex Tester

Frequently asked questions

References

• Playwright DocumentationMicrosoft (Playwright)Official documentation for Playwright, an end-to-end test framework that drives Chromium, WebKit and Firefox.
• Best Practices — PlaywrightMicrosoft (Playwright)Test user-visible behaviour, keep tests isolated, prefer resilient locators and web-first assertions, and debug with traces.
• ISTQB GlossaryISTQBThe standard definitions of testing terms — test case, regression testing, severity, priority, boundary value analysis and the rest.
• Cypress DocumentationCypress.ioOfficial documentation for end-to-end and component testing in the browser with Cypress.