Rendering emails in tests fails if sync in v5

[rothsandro]

Hi 👋,

After updating to React Email v5 the tests with Vitest + Happy DOM fail. If I make the first test in each test file async with screen.findBy*, this and all following tests in the file are successful. This creates a dependency between the tests, they can't be executed independently anymore.

Is this an expected behavior and what's the correct way to handle this? Should we make all tests async or is there a way to "prepare" react-email (I assume the first test loads some additional code or something like that?) upfront so that the tests can by synchronous?

Repro: https://github.com/rothsandro/repro.react-email-test/tree/main/emails

[apoorva-01]

This is expected in v5, and it's the <Tailwind> component doing it, not your test setup.

In v5 <Tailwind> compiles the CSS through an async step and suspends on the first render (it throws a promise via an internal useSuspensedPromise hook). Testing Library's render() returns synchronously, so on that very first render the tree is still suspended and nothing has committed yet, which is why getByText finds nothing. findByText works because it polls until React re-renders after the promise resolves.

The reason the rest of the file then passes synchronously: that hook caches the resolved result in a module-level map keyed by config. Once the first render has awaited it, every later render in the same worker gets the compiled result back instantly, no suspend. So the whole thing hinges on "has anything awaited the Tailwind compile yet in this worker," which is exactly the cross-test dependency you're seeing.

So don't make the tests sync. Await the render in each one:

test("test 1", async () => {
  render(<Email />);
  expect(await screen.findByText("Join the team")).toBeTruthy();
});

findBy* returns a promise and retries under the hood, so each test independently waits for the suspended render to settle and they stop depending on order. If you'd rather not touch every test, warm it once so the cache is populated before your real tests run:

beforeAll(async () => {
  render(<Email />);
  await screen.findByText("Join the team");
  cleanup();
});

Either works. I'd go with findBy* everywhere since it's the honest "email render is async" model and it keeps tests independent.

[rothsandro]

Thanks 🙏