Support for React Server Components

[remy90]

Describe the feature you'd like:

As a user of react 18 with NextJS (with app directory), I would like to render async server components

example:
// Page.tsx

const Page = async ({ params, searchParams }: PageProps) => {
    const asyncData = await fetchSomeDataAsynchronously()
    return (<foo {...asyncData} />
}

...
// Page.test.tsx

it('should render', () => {
    render(<Page />)
    expect(screen....).ToBe(....)
})

Extracting server page logic would be an alternative, but I think that would also significantly reduce the purpose of RTL if that were to become an encouraged architectural default.

Current progress, workarounds, and demo

[prakashtiwaari]

You can use like this:

it('should render', async() => {
    render(<Page />);
    await waitFor(()=> {
      expect(screen....).ToBe(....)
    });
});

[remy90]

@prakashtiwaari Not quite.

It's render that's giving the issue. To provide the full error message:

'Page' cannot be used as a JSX component.
  Its return type 'Promise<Element>' is not a valid JSX element.
    
Type 'Promise<Element>' is missing the following properties from type 'ReactElement<any, any>': type, props, keyts(2786)

[remy90]

A friend came up with the following:

const props = {
  params: { surveyType: '123' },
  searchParams: { journeyId: '456' },
}

const Result = await Page(props)
render(Result)

I'll wait for a moderator to close this but it would be nice to have async components supported inside render

[nickserv]

A friend came up with the following:

const props = {
  params: { surveyType: '123' },
  searchParams: { journeyId: '456' },
}

const Result = await Page(props)
render(Result)

I'll wait for a moderator to close this but it would be nice to have async components supported inside render

I like this idea personally. It should be easy enough to introspect if a component is async by determining if it returns a Promise. Then we can await the Promise internally and either return a Promise in render or poll to return synchronously.

[Gpx]

For those that are trying to mock API responses, this seems to be working for now:

test("should do stuff", async () => {
  global.fetch = jest.fn().mockResolvedValue({
    json: jest.fn().mockResolvedValue({ login: "Gio" }),
  });
  render(await Page());
  expect(screen.getByText("Hi Gio!")).toBeInTheDocument();
});

If you don't define global.fetch, you get ReferenceError: fetch is not defined.

I would love to be able to use MSW, but that's still not working with Next's model. See: https://twitter.com/ApiMocking/status/1656249306628915208?s=20

On a side note, even if we make this work, there's the issue of Next layout composition. If I render a Page component in my test, I most likely want to render also its layout(s). I understand this is not necessarily a concern that RTL should have, but we should keep it in mind. Next could provide an API for testing that builds the whole rendering tree.

[nickserv]

We could document using layouts similarly to how we already document using providers: by importing them and passing them as the wrapper option of render.

import {render} from '@testing-library/react'
import Layout from './layout'
import Page from './page'

render(<Page />, {wrapper: Layout})

@Gpx has a good point that rendering nested layouts would be more challenging. We could try to expose an abstraction, but the paths to import from would be dynamic and depend on Next patterns. If this isn't practical, we can open an issue with Next upstream and ask for an API to consume internally.

Also if we change render to be compatible with returning promises, we should probably ship a breaking change so end users are aware they may need to change their tests (especially if they're using TypeScript).

[Gpx]

I agree we should ask Next to provide an API. I'm thinking something like this:

const RSC = routeComponent('/some/path') // This will return an RSC with all nested layouts passing the correct props
render(RSC)

// With additional props
const RSC = routeComponent('/some/path', { foo: 1 })
render(RSC)

WDYT?

---

As for the breaking change, won't this be a feature? I don't think anyone was relying on render breaking for async components.

[nickserv]

I'm doing more research into RSCs using Next, and I noticed some mistaken assumptions I had:

1. Determining if a component uses suspense is not possible due to the halting problem as it would be valid for the component to sometimes not return a Promise, and we can't distinguish between a component not returning a Promise currently vs. ever.
2. The new rendering async APIs don't return Promises, they return streams. So, we don't necessarily need to make our render function async, though we may need to poll to unwrap streams synchronously.

Overall, I think supporting React server components involves figuring out the following concerns:

1. [react] Allow returning ReactNode from function components DefinitelyTyped/DefinitelyTyped#65135
2. Figuring out how we can internally render async components (may involve using a different render API, and would require using experimental/canary React right now)
3. Supporting bundling and routing strategies from different frameworks (we could use the adapter pattern to compose APIs from RSC frameworks such as Expose method to render whole route tree in testing vercel/next.js#50479)

[nickserv]

I agree we should ask Next to provide an API. I'm thinking something like this:

const RSC = routeComponent('/some/path') // This will return an RSC with all nested layouts passing the correct props
render(RSC)

// With additional props
const RSC = routeComponent('/some/path', { foo: 1 })
render(RSC)

WDYT?

@Gpx Shouldn't that be render(<RSC />)? Also are you suggesting the URL path or filesystem path here?

[tom-sherman]

The idea to render the server component as async client components seems to be the best idea I've seen so far.

I don't think it's suitable for RTL to bake Next.js' (or any other framework's) semantics into it's API. Async client components solve this by being agnostic of any framework.

I think this would retain the current RTL API with maybe the addition of a suspense wrapper - rendering nothing initially could be confusing so enforcing a fallback makes sense.

render(<Page />) // throws an error because there's no boundary (I think this would be default react behaviour)
render(<Suspense><Page /></Suspense>) // This would be ok

[tom-sherman]

I do think it's easier to just mount the server component as a client component with createRoot though - this works in react-dom canary today.

See commit on your test repo here: tom-sherman/rsc-testing@9e4aa67

I'm not sure how RTL can support rendering of the root layout in Next.js, but as I said before I don't think it should - at least not part of it's core API. The root layout returning <html> is a Next.js-specific idiom, not all server component frameworks choose to work this way.

[nickserv]

Thanks for the branch, that's interesting. I'd still like to understand why this works and onAllReady doesn't though, as that's supposed to be used for SSG where having suspense fallbacks everywhere wouldn't be accessible. Also, while I understand why your version of the test needs to await for a suspended render, I'd rather not make end users worry about understanding this if there's a way to ensure certain components load automatically. Additionally, both branches still have act warnings, though I have no idea how to fix this as I've already tried using it in various ways.

[tom-sherman]

Also, while I understand why your version of the test needs to await for a suspended render, I'd rather not make end users worry about understanding this if there's a way to ensure certain components load automatically

You're going to need an await somewhere - you can't syncronously block because it's an async component. I suppose you could have a builtin suspense boundary and have the user await render(<Page />) but as soon as the user adds a suspense boundary somewhere they're gonna need to use waitFor anyway.

[nickserv]

That's closer to what I was thinking originally. Though, I think I'm confused about how this is working, but I'll reply here again when I resolve it.

[Gpx]

I agree we should ask Next to provide an API. I'm thinking something like this:

const RSC = routeComponent('/some/path') // This will return an RSC with all nested layouts passing the correct props
render(RSC)

// With additional props
const RSC = routeComponent('/some/path', { foo: 1 })
render(RSC)

WDYT?

@Gpx Shouldn't that be render(<RSC />)? Also are you suggesting the URL path or filesystem path here?

No, I think it should be render(RSC) where RSC is something like <Component {...nextProps} >. Alternatively routeComponent could return a component and its props:

const { Component, props } = routeComponent('/some/path')
render(<Component {...props} />)

We need not only the components tree but also the props that Next is passing.

---

The URL should be passed to the method, not the filesystem path. If we want to simulate a real user interacting with the app they'll use URLs.

---

To be clear, I'm not saying we should implement this in RTL, but rather that we should ask the Next team to provide it since it will be helpful for anyone doing tests.

[nickserv]

I'm not sure we need it to return params, since you can just choose what params to render in your test by changing the URL.

[Gpx]

I'm not sure we need it to return params, since you can just choose what params to render in your test by changing the URL.

Say you want to test the URL /foo/bar/baz. What are the params? Well, it depends on your file system:

Route	params
app/foo/[slug]/baz	{ slug: 'bar' }
app/foo/bar/[slug]	{ slug: 'baz' }
app/foo/[[...slug]]	{ slug: ['bar', 'baz'] }

I can create the params object in my tests and pass it to the component, but if later I modify the filesystem, I might break my code, and my tests will still work.

If we want to keep the render(<Component />) format rather than render(Component) Component could just render the tree passing the correct params.

[tom-sherman]

Do we agree that RTL (at least in the core API) shouldn't support this kind of routing stuff? If so probably best to split that conversation out into a different issue?

[nickserv]

If we want to keep the render(<Component />) format rather than render(Component) Component could just render the tree passing the correct params.

@Gpx Yes, I think that's simpler, and I'd rather avoid exposing the implementation detail of param values.

Do we agree that RTL (at least in the core API) shouldn't support this kind of routing stuff? If so probably best to split that conversation out into a different issue?

@tom-sherman I'm not suggesting we add a Next specific app router API directly into Testing Library. However, I'd like us to have either docs or some sort of adapter/facade/etc. design pattern that composes a Next routing primitive.

[nickserv]

The demo seems to work great with React 19 RC! 😄

[david-zenx]

how to test the server components in nextjs using jest , can anyone give me an example?

[Stan-Stani]

@nickmccurdy

Reminder: We recommend integration testing, rather than unit testing, without mocking components.

I'm sorry, but I don't understand what you're saying. Concerning the case where we have nested async components in the component we are testing, how are we supposed to avoid errors like Error: Uncaught [Error: Objects are not valid as a React child (found: [object Promise]). If you meant to render a collection of children, use an array instead.] ? I thought the whole point of mocking in this situation was to avoid those errors?

ETA: Ah, I think this is the solution: > @Ruffeng Please use the workarounds, they properly use React canary to support nested components. Anything else will require reimplementing async components, which is not worth it for Testing Library or any end user to support.

All these hidden comments make following the conversation confusing...

[nickserv]

how to test the server components in nextjs using jest , can anyone give me an example?

@david-zenx The workarounds and demo still support Jest!

[nickserv]

All these hidden comments make following the conversation confusing...

@Stan-Stani I've been trying to keep this issue as clean and on topic as I reasonably can, as there have been some resolved, duplicate, and off topic replies, and this has been important for reference and historical documentation. Sorry if that's confusing, but you probably don't have to worry about hidden replies if you read other replies (especially the workarounds). Let me know if you have any additional questions or feedback, though.

[kasperpeulen]

I had some helpful suggestions from the React team on how to start up an RSC server with full support for React RSC features (excluding Next specific features for now). I'm developing a renderServer function that simulates a React server with our existing React client.

@nickserv I am wondering if you are still planning to do this. We are using your mentioned workaround as the official solution in storybook, as storybook runs in the browser and our playwright based test runner as well.

It works actually susprisingly well. We have a storybook demo here:
https://github.com/storybookjs/storybook-rsc-demo

However some libraries uses react-server conditions for their exports. So that you can not accidently import stuff meant only for RSC on the client:

• apollo-client-nextjs - repo - (react-server export)
• react-hook-form - (repo) - (react-server export)

If more and more libraries are gonna adopt the react-server convention, then this solution would become problematic.

Just wondering what you’re thoughts are on this matter, as it seems you have been thinking about it for quite some time!

[abel-castro]

I can confirm the workaround works.

In addition, I believe I’ve discovered an issue when using snapshots with Vitest and async react server components.

For example here the snapshots were being generated as an empty <div />.

test("Having `<Layout>` here will generate an empty snapshot", async () => {
	const { container } = render(
		<Suspense>
			<Layout>
				<Page />
			</Layout>
		</Suspense>,
	);
	await screen.findByText("server");
	expect(container).toMatchSnapshot();
});

test("Don't using screen here will generate an empty snapshot", async () => {
	const { container } = render(
		<Suspense>
			<Layout>
				<Page />
			</Layout>
		</Suspense>,
	);

	expect(container).toMatchSnapshot();
});

My workaround was to first perform some screen assertions. After doing this, the snapshots are generated correctly when using toMatchSnapshot.

test("Removing the `<Layout>` tag and calling screen will generate a correct snapshot", async () => {
	const { container } = render(
		<Suspense>
			<Page />
		</Suspense>,
	);
	await screen.findByText("server");
	expect(container).toMatchSnapshot();
});

I created a pull-request that adds those examples to @nickserv demo.

[chrisbruford]

@abel-castro any trick to getting this to work? wrapping it in a Suspense was insufficient for me - I still got an error about trying to render a Promise

[sroebert]

@abel-castro any trick to getting this to work? wrapping it in a Suspense was insufficient for me - I still got an error about trying to render a Promise

This is still working great for us: #1209 (comment)

[aurorascharff]

@abel-castro any trick to getting this to work? wrapping it in a Suspense was insufficient for me - I still got an error about trying to render a Promise

For me the problem has been that the React version is not correct - something happens when installing Next.js RC, it becomes overwritten. You can check it by throwing a console.log(React.version) into a test. If it is not using React 19, run npm install react@rc react-dom@rc again (even though you already have React RC in your dependencies).

[abel-castro]

@abel-castro any trick to getting this to work? wrapping it in a Suspense was insufficient for me - I still got an error about trying to render a Promise

I agree with @aurorascharff. As mentioned in previous comments, to make this work, it’s currently necessary to use some edge versions of React, ReactDOM, and Next.js. For reference, you can check the versions used by @nickserv in his demo.

"dependencies": {
    "next": "^15.0.0-rc.0",
    "react": "canary",
    "react-dom": "canary",
    ...

[aurorascharff]

@abel-castro any trick to getting this to work? wrapping it in a Suspense was insufficient for me - I still got an error about trying to render a Promise

I agree with @aurorascharff. As mentioned in previous comments, to make this work, it’s currently necessary to use some edge versions of React, ReactDOM, and Next.js. For reference, you can check the versions used by @nickserv in his demo.

"dependencies": {
    "next": "^15.0.0-rc.0",
    "react": "canary",
    "react-dom": "canary",
    ...

This did not work for me, I had to install the fresh one with npm install react@rc react-dom@rc. It gave me:

"react": "^19.0.0-rc-3208e73e-20240730",
"react-dom": "^19.0.0-rc-3208e73e-20240730",

[nickserv]

At this point my resources are limited. I'm disabled and out of savings, so I have to work part time and spend less time on open source. I also have many RSC projects with not nearly enough energy to finish them. At this point the best way to ensure I can work on this soon is to sponsor me (like Kent C. Dodds and Artem Zakharchenko have), otherwise I'll be prioritizing the workaround and other projects which are much simpler.