eslint-plugin-testing-library/await-async-events for method calls on user-event instances created with setup()

[spicattutti]

Context

• we have test helpers that create an instance of user-event using setup
• the test helper is in place to render components with certain decorations, while allowing overrides of options
• we also do the setup call because we see it's recommended Is there some guidance on when to use `setup()` vs `userEvent.whatever`? user-event#1036

const { user } = renderWithTheme(<FooComponent/>, {
      userEventOptions: {
        delay: 1,
      },
    });

• we have flaky tests because await-async-events does not enforce missing awaits for user.click() (where user is created like shown above, only for the case of using exported APIs

import userEvent from "@testing-library/user-event";
userEvent.click // eslint complains

Problem

• we get flaky tests because of forgotten awaits
• we cannot enforce using await on click, type etc using TS and eslint without enabling require-await, which would be painful to enable

TS test helpers:

// import type { Asyncify } from "type-fest";

type UserSetupResult = Omit<
  ReturnType<typeof userEvent.setup>,
  "click" | "type"
> & {
  click: Asyncify<typeof userEvent.click>;
  type: Asyncify<typeof userEvent.type>;
  // ...
};

eslint config:

      // use base rule (instead of `@typescript-eslint/require-await` to speed up runs
      "require-await": "error",

• we can also not just return the raw userEvent object in our test helper in case of no override for options, because the setup call is recommended, as mentioned above

Question

Has anyone solved this?

[Belco90]

Hey @spicattutti! If you are using TS, what about @typescript-eslint/no-floating-promises rule?

[Samielakkad]

@typescript-eslint/no-floating-promises is the cleanest solution here if your helper returns a correctly typed user from userEvent.setup().

testing-library/await-async-events is mostly syntax/AST based: it can catch direct known Testing Library / userEvent imports, but it cannot reliably prove that an arbitrary variable returned from a custom helper is a user-event setup instance. Once the call looks like user.click(...), the plugin would need type-aware alias tracking across your helper boundary to know that user is the async user-event object.

So I would solve this at the TypeScript promise level, not with require-await:

// eslint.config.js
export default tseslint.config(
  // ...your other config
  {
    files: ["**/test/**/*.test.{ts,tsx}"],
    rules: {
      "@typescript-eslint/no-floating-promises": "error",
    },
  },
);

Then make sure the helper preserves the real setup return type instead of widening it:

import userEvent from "@testing-library/user-event";

type RenderWithThemeResult = {
  user: ReturnType<typeof userEvent.setup>;
  // other render result fields...
};

With that, forgotten awaits like this should be caught because user.click(...) returns a Promise:

user.click(button); // no-floating-promises error
await user.click(button); // ok

If you have intentional fire-and-forget cases, mark them explicitly with void user.click(...), though for user-event calls in tests that is usually a smell.

One tradeoff: no-floating-promises needs type information, so it is heavier than a purely syntactic rule. I would scope it to test files first instead of enabling it globally.