Assertions

Assertions groups the ready-to-use checks applied to a component and one of its element keys.

In practice, this namespace makes it possible to write expectations that are more readable and more consistent than a sequence of Playwright calls scattered across the tests.

Simple example

import { Assertions, createComponent, createWebsite, type Website } from "@duplojs/playwright";
import test from "playwright/test";

interface TestFixtures {
	website: Website;
}

const testClient = test.extend<TestFixtures>({
	async website({ page, context }, use) {
		const website = createWebsite({
			playwrightPage: page,
			playwrightBrowserContext: context,
			envConfig: {
				baseUrl: "https://example.com",
			},
		});

		await use(website);
	},
});

const searchForm = createComponent(
	"searchForm",
	{
		getMainElement({ body }) {
			return body.locator("[data-search-form]");
		},
		getElements({ mainElement }) {
			return {
				query: mainElement.locator("input"),
				submit: mainElement.locator("button[type='submit']"),
			};
		},
	},
);

testClient("assertions example", async({ website }) => {
	const component = await website.iWantToSee(searchForm);

	await Assertions.toHaveValue(component, "query", "duplojs");
	await Assertions.toBeVisible(component, "submit");
});

What is happening here

• the component exposes named elements
• Assertions.toHaveValue(...) and Assertions.toBeVisible(...) target these elements directly
• the test stays focused on business verification rather than technical details

What is it for?

Assertions is mainly used to:

• share frequent expectations
• keep a consistent vocabulary in tests
• avoid repeating the same assertion sequences
• centralize enriched checks such as prior visibility

toBeVisible

Assertions.toBeVisible(component, elementKey)

Checks that an element is visible.

toHaveText

Assertions.toHaveText(component, elementKey, text)

Checks that an element has exactly the expected text.

toContainText

Assertions.toContainText(component, elementKey, text)

Checks that an element contains the expected text.

toHaveNoText

Assertions.toHaveNoText(component, elementKey)

Checks that an element has no text.

toBeHidden

Assertions.toBeHidden(component, elementKey)

Checks that an element is hidden.

toHaveQuantity

Assertions.toHaveQuantity(component, elementKey, {
  quantity,
  operator?,
})

Checks the number of elements matching a locator.

toBeEnabled

Assertions.toBeEnabled(component, elementKey)

Checks that an element is enabled.

toBeChecked

Assertions.toBeChecked(component, elementKey)

Checks that an element is checked.

toBeDisabled

Assertions.toBeDisabled(component, elementKey)

Checks that an element is disabled.

toHaveAttribute

Assertions.toHaveAttribute(component, elementKey, name, value?)

Checks that an element has an expected attribute.

toHaveClass

Assertions.toHaveClass(component, elementKey, value)

Checks that an element has the expected class.

toHaveValue

Assertions.toHaveValue(component, elementKey, value)

Checks that an element has the expected value.

toBeBusy

Assertions.toBeBusy(component, elementKey)

Checks that an element has aria-busy="true".

toBeNotBusy

Assertions.toBeNotBusy(component, elementKey)

Checks that an element has aria-busy="false".

withStep

Assertions.withStep(label).assertion(component, elementKey, ...args)

Returns the same assertions, but grouped under a custom test.step(...). The useful call is then chained on the returned wrapper.

See also

• Actions - for ready-to-use interactions on components.
• Component - to define the elements the assertions apply to.
• Component Interaction - to create custom checks if the provided assertions are not enough.