User events

In its current state, our discount form component test gives you some value, but it can give so much more. We don't create UI elements simply for them "to be" on the page. They are there so our users can interact with them, make them do something, and help them achieve their tasks.

The main purpose of the discount form component is to apply the given discount code. That is what has to be reflected in automated tests.

First, I will rename the test case name to reflect the changes I'm about to make:

test('renders the discount form', async () => {
test('applies a discount code', async () => {

🦉 Check out the How to write better test names talk to learn about 5 tips for stellar test names.

Next, in the discount-code-form.browser.test.tsx, I will start by renaming the test case to reflect what I am testing here.

test('renders the discount form', async () => {
test('applies a discount code', async () => {

Then, I am going to remove the following visibility assertion:

test('applies a discount code', async () => {
	render(<DiscountCodeForm />)

	const discountInput = page.getByLabelText('Discount code')
	await expect.element(discountInput).toBeVisible()

I intend to interact with the discountInput element so asserting its visibility on the page is redundant. Its interactivity is implied by the interaction. If this input is, say, not being rendered correctly, interacting with it will fail. This is called an implicit assertion.

🦉 Implicit assertions are a great way to achieve more in tests while writing less.

To actually enter the discount code into the input, I will use the .fill() method on that element's locator:

test('applies a discount code', async () => {
	render(<DiscountCodeForm />)

	const discountInput = page.getByLabelText('Discount code')
	await discountInput.fill('EPIC2025')

The .fill() method accepts a value to enter and returns a promise that resolves when the browser is finished typing it in.

Now that the discount code has been entered, it's time to apply it.

As above, I will drop the redundant visibility assertion from the applyDiscountCode button, and replace it with the .click() interaction with that button:

test('applies a discount code', async () => {
	render(<DiscountCodeForm />)

	const discountInput = page.getByLabelText('Discount code')
	await discountInput.fill('EPIC2025')

	const applyDiscountButton = page.getByRole('button', {
		name: 'Apply discount',
	})
	await expect.element(applyDiscountButton).toBeVisible()
	await applyDiscountButton.click()

Clicking on the button submits the discount form, making it do whatever it has to do to apply the given discount code. All that's left for me is to assert that the applied code is correctly displayed to the user.

My expectation here is derived from how the applied discount code is displayed. If I take a look at the

discount-code-form.tsx

component, I can see that the code gets displays like so:

{appliedDiscount ? (
	<p>
		Discount: <strong>{appliedDiscount.code}</strong> (-
		{appliedDiscount.amount}%)
	</p>
) : {
	/* ... */}
)

Finally, when the code has been successfully applied, I expect this paragraph to be visible on the page:

test('applies a discount code', async () => {
	render(<DiscountCodeForm />)

	const discountInput = page.getByLabelText('Discount code')
	await discountInput.fill('EPIC2025')

	const applyDiscountButton = page.getByRole('button', {
		name: 'Apply discount',
	})
	await expect.element(applyDiscountButton).toBeVisible()
	await applyDiscountButton.click()

	await expect
		.element(page.getByText('Discount: EPIC2025 (-20%)'))
		.toBeVisible()
})

This completes the test! 🎉

Locator methods vs `userEvent`

If you used React Testing Library in the past, you've likely been interacting with your components via the userEvent object from @testing-library/user-event. Vitest provides you a similar object from the @vitest/browser/context package:

import { userEvent } from '@vitest/browser/context',

test('applies a discount code', async () => {
	const applyDiscountButton = page.getByRole('button', {
		name: 'Apply discount',
	})
	await userEvent.click(applyDiscountButton)
})

📜 The two userEvent objects behave slightly differently. I recommend you read Interactivity API to learn that difference.

You might have noticed that in this exercise you've used locator methods directly:

await applyDiscountButton.click()

Either way is fine. Vitest binds all userEvent actions to the underlying locators, which means that locator.click() is translated to userEvent.click(locator) under the hood.

Using locator methods directly is a faster way to get common interactivity like clicking or typing. The userEvent object exposes additional interactivity methods that are not present as locator methods:

.tab()
.keyboard()
.upload()
.cut() and .paste()
and others

Prefer built-in locator methods where availabile, and rely on the userEvent methods otherwise.

03. Best practices/02. User events (🏁 solution)

User events

Locator methods vs userEvent

Locator methods vs `userEvent`