Best practices when using userEvent and asynchronous queries and assertions in interaction testing, e.g. await expect, canvas.findBy, await waitFor() with Storybook Test Runner (not Vitest addon)

[ahayes91]

Some background:

• I'm getting started with interaction tests with Storybook Test Runner for the first time
• I'm not using the Vitest addon because it doesn't yet support screenshot testing and image comparison (unlike jest-image-snapshot which still works with Storybook Test Runner like in this blog and Storybook v8 docs)
• I'm having some trouble establishing best practices on async syntax and use of userEvent in my play functions.

Async queries and assertions in Vitest/Jest non-browser mode versus play functions in Storybook

https://testing-library.com/docs/dom-testing-library/api-async/ has some good documentation about when to use findBy queries and await waitFor for more synchronous checks which I'm used to following when writing unit tests in Vitest/Jest (non-browser mode).

Now that I'm starting to write interaction tests in Storybook through the play function, I see that expect from storybook/test is asynchronous, so it's less clear now about what we can / can't / shouldn't do.

For example, I knew in Jest / Vitest (non-browser mode) something like the following would never actually "wait" for something to appear because expect is synchronous:

// incorrect, won't actually wait for screen to find something and runs immediately - could fail if the button doesn't exist
expect(await screen.findByRole('button')).toBeVisible();

// correct, use waitFor to retry the assertion until it is true
await waitFor(() => {
  expect(screen.getByRole('button')).toBeVisible();
});

This was particularly relevant for an assertion like toBeVisible() which does a lot more than toBeInTheDocument().

What is the correct way to use await expect and await waitFor now, particularly with toBeVisible() assertions?

// Would this work?
await expect(await canvas.findByRole('button', {name: 'Click me!'})).toBeVisible();

// Is this better?
await expect(canvas.getByRole('button', {name: 'Click me!'})).toBeVisible();

// Anything wrong with this?
await waitFor(async () => {
  await expect(canvas.getByRole('button', {name: 'Click me!'})).toBeVisible();
});

// This seems like a lot?
await waitFor(async () => {
  await expect(await canvas.findByRole('button', {name: 'Click me!'})).toBeVisible();
});

Where should we import userEvent from?

There are conflicting examples about getting userEvent from the play function versus importing it directly from storybook/test.

Using the example from https://storybook.js.org/docs/writing-tests/interaction-testing#writing-interaction-tests:

import {expect} from 'storybook/test';
...
export const FilledForm: Story = {
  play: async ({ canvas, userEvent }) => {
    // 👇 Simulate interactions with the component
    await userEvent.type(canvas.getByTestId('email'), 'email@provider.com');
 
    await userEvent.type(canvas.getByTestId('password'), 'a-random-password');
 
    // See https://storybook.js.org/docs/essentials/actions#automatically-matching-args to learn how to setup logging in the Actions panel
    await userEvent.click(canvas.getByRole('button'));
 
    // 👇 Assert DOM structure
    await expect(
      canvas.getByText(
        'Everything is perfect. Your account is ready and we should probably get you started!',
      ),
    ).toBeInTheDocument();
  },
};

For userEvent, is there a functional difference between that and importing it from storybook/test, e.g.:

import {expect, userEvent} from 'storybook/test';
...
export const FilledForm: Story = {
  play: async ({ canvas }) => {
    // 👇 Simulate interactions with the component
    await userEvent.type(canvas.getByTestId('email'), 'email@provider.com');
 
    await userEvent.type(canvas.getByTestId('password'), 'a-random-password');
 
    // See https://storybook.js.org/docs/essentials/actions#automatically-matching-args to learn how to setup logging in the Actions panel
    await userEvent.click(canvas.getByRole('button'));
 
    // 👇 Assert DOM structure
    await expect(
      canvas.getByText(
        'Everything is perfect. Your account is ready and we should probably get you started!',
      ),
    ).toBeInTheDocument();
  },
};

The second one seems to work for me in my testing, and I favour it a bit more because it's more like imports from @testing-library/react that I'm used to in unit tests.

Thanks!

[dosubot[bot]]

Here are the current best practices for async queries, assertions, and userEvent usage in Storybook Test Runner play functions:

Async assertions and queries:

• Use await expect(await canvas.findByRole(...)).toBeVisible() when you expect the element to appear asynchronously. This waits for the element and then asserts visibility, which is the most direct and reliable pattern for Storybook play functions [docs].
• await expect(canvas.getByRole(...)).toBeVisible() works if you know the element is already present. If the element might not be there yet, prefer the findBy pattern above.
• await waitFor(() => expect(canvas.getByRole(...)).toBeVisible()) is also valid and retries the assertion until it passes or times out. However, avoid mixing await expect(await findBy...) inside waitFor—that’s redundant and unnecessary [docs].
• Always await your expect calls in play functions. Storybook’s expect is asynchronous and this ensures proper logging and debugging in the Interactions panel [docs].

userEvent usage:

• You can use userEvent from the play function context (play: async ({ canvas, userEvent }) => { ... }) or import it directly from 'storybook/test'. Both are functionally equivalent in the Test Runner [docs], [example].
• Importing from 'storybook/test' is recommended for consistency and integration with Storybook’s environment, but importing from @testing-library/user-event also works if you prefer that style.
• Always await userEvent methods (e.g., await userEvent.click(...)) to ensure correct sequencing and logging [docs].

Your code examples:

• ✅ await expect(await canvas.findByRole('button', {name: 'Click me!'})).toBeVisible(); — recommended for waiting for the button to appear and then asserting visibility.
• ✅ await expect(canvas.getByRole('button', {name: 'Click me!'})).toBeVisible(); — works if the button is already present.
• ✅ await waitFor(() => expect(canvas.getByRole('button', {name: 'Click me!'})).toBeVisible()); — valid, but usually not needed if you use findBy.
• 🚫 await waitFor(async () => { await expect(await canvas.findByRole(...)).toBeVisible(); }); — redundant, as findBy already waits.

Example pattern:

import { expect, userEvent } from 'storybook/test';

export const Example = {
  play: async ({ canvas }) => {
    await userEvent.click(await canvas.findByRole('button', { name: 'Open dialog' }));
    const dialog = await canvas.findByRole('dialog');
    await expect(dialog).toBeVisible();
  },
};

This approach matches official Storybook templates and documentation [example].

You’re set to use either import style for userEvent, but sticking with storybook/test is the most consistent with Storybook’s own examples.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[ahayes91]

For this part:

await expect(canvas.getByRole(...)).toBeVisible() works if you know the element is already present. If the element might not be there yet, prefer the findBy pattern above.

I guess that means that the Storybook expect does not have any retries or timeouts built into it, in the same way that expect from Vitest in browser mode does? https://www.epicweb.dev/incredible-vitest-defaults

I think I've having trouble distinguishing between the Vitest browser mode expect and the Jest expect too - I presume Jest expect is what kicks in when you use Storybook Test Runner. How does Storybook expect work under the hood?

[dosubot[bot]]

You're correct—Storybook's expect (from storybook/test) does not have built-in retries or timeouts. It runs assertions immediately, just like Jest's expect, and does not poll or retry for conditions to become true. This means if you write await expect(canvas.getByRole(...)).toBeVisible(), it will only pass if the element is already present and visible at that moment. If the element appears asynchronously, you need to use findBy queries or wrap your assertion in waitFor to handle waiting logic.

Under the hood, Storybook's expect is a custom, instrumented version that combines Chai assertions with a subset of Jest-style matchers, and is instrumented for Storybook's Interactions panel and debugging tools. It is not a direct wrapper around Jest's or Vitest's expect, but its behavior is closest to Jest's: no retries or polling by default, and no snapshot matchers like toMatchSnapshot [source] [docs].

Vitest's expect (especially in browser mode) can have built-in retries for certain assertions, which is a key difference. In Storybook play functions, always use findBy or waitFor for anything that might appear asynchronously, and always await your expect calls for proper logging and debugging [docs].

If you want to see the implementation, check out code/core/src/test/expect.ts in the Storybook repo.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[ahayes91]

Thank you! This bit seems to contradict what you said earlier though:

You're correct—Storybook's expect (from storybook/test) does not have built-in retries or timeouts. It runs assertions immediately, just like Jest's expect, and does not poll or retry for conditions to become true. This means if you write await expect(canvas.getByRole(...)).toBeVisible(), it will only pass if the element is already present and visible at that moment.

Doesn't that mean that await expect(await canvas.findByRole('button', {name: 'Click me!'})).toBeVisible(); would not work if the element was not visible when it is first found by the findBy command?

Perhaps a better example is an assertion like toHaveFocus(), which could be delayed even when the element can be found asynchronously - it seems to be like the only way to truly assert that would be to use waitFor?

await waitFor(() => expect(canvas.getByRole('button', {name: 'Click me!'})).toHaveFocus());

[dosubot[bot]]

You're right—findByRole only waits for the element to exist in the DOM, not for it to be visible or focused. So, await expect(await canvas.findByRole('button', { name: 'Click me!' })).toBeVisible(); will fail if the button is present but not visible at that moment. The same goes for toHaveFocus: if focus is delayed, the assertion will fail unless the element is already focused when found.

For any condition that might become true after the element is present (like visibility after an animation, or focus after a user event), wrap your assertion in waitFor. This will retry the assertion until it passes or times out:

await waitFor(() => expect(canvas.getByRole('button', { name: 'Click me!' })).toHaveFocus());

This is the recommended pattern for delayed conditions in Storybook play functions, and you’ll see it used in official examples and code [docs] [example] [PR].

So, use findByRole for presence, and waitFor for any state (like visibility or focus) that might not be immediate.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[ahayes91]

One thing - when I made a code change today to use

await waitFor(() => expect(canvas.getByRole('button', { name: 'Click me!' })).toHaveFocus());

I saw an eslint error:

Promises must be awaited, end with a call to .catch, end with a call to .then with a rejection handler or be explicitly marked as ignored with the `void` operator.eslint[@typescript-eslint/no-floating-promises](https://typescript-eslint.io/rules/no-floating-promises)

To fix that, I have to use the following syntax - is this correct?

await waitFor(async () => await expect(canvas.getByRole('button', { name: 'Click me!' })).toHaveFocus());

[dosubot[bot]]

Yes, your fix is correct and matches Storybook's recommended usage. When using waitFor with Storybook's async expect (which returns a Promise), you should use an async callback and await the expect call inside it. This resolves the eslint no-floating-promises error and ensures proper sequencing and logging in the Interactions panel [example] [example].

So this pattern is best practice:

await waitFor(async () => {
  await expect(canvas.getByRole('button', { name: 'Click me!' })).toHaveFocus();
});

There are no Storybook-specific linting overrides for this, so using an async callback and awaiting expect is the right approach.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}