Relay E2e Test

Relay E2E Tests

Markdown-driven end-to-end tests for Relay. Each test is a self-contained .md file that defines a GraphQL server (via Grats), a Relay-powered React component, and optional interaction steps. The test harness extracts the code blocks, compiles them with Grats + relay-compiler, renders with React Testing Library, runs interactions, and snapshot-tests the output.

Tests run against Relay runtime packages from source, so changes are reflected immediately without a build step.

References

Read the appropriate reference file based on your task:

• [Writing fixtures](references/writing-fixtures.md) — fixture format, example, server/client code patterns, interaction DSL, snapshots. Read when creating or modifying test fixtures.
• [Running tests (internal)](references/running-tests-internal.md) — setup, commands, and compiler resolution for fbsource / OD. Read when running tests internally.
• [Running tests (GitHub)](references/running-tests-github.md) — setup, commands, and compiler resolution for the OSS repo. Read when running tests on GitHub.

Running E2E Tests (GitHub / OSS)

Directory layout

First-time setup

yarn install --frozen-lockfile --ignore-scripts
yarn build
cd packages/relay-e2e-test && yarn install

Commands

All commands run from the repo root.

Run all e2e tests:

yarn test:e2e

Run a single fixture by name (use the path without extension, e.g. queries/greeting):

yarn test:e2e -- --testNamePattern greeting

Compiler resolution

The test harness resolves the relay-compiler binary in this order:

1. RELAY_COMPILER_BINARY env var 2. Local cargo build: compiler/target/debug/relay 3. npm fallback: node_modules/.bin/relay-compiler

To test compiler changes, build with cargo build --manifest-path=compiler/Cargo.toml --bin relay and re-run tests.

Running E2E Tests (Internal / fbsource)

Directory layout

The test harness resolves these paths transparently via resolveRelayPackage() in repoRoot.js and findBabelPluginRelay() in jest-transform.js.

First-time setup

cd xplat/js/RKJSModules/Libraries/Relay/oss/__github__

# 1. Install root dependencies
yarn install --ignore-scripts --ignore-engines

# 2. Install e2e package dependencies (includes babel-plugin-relay from npm)
cd packages/relay-e2e-test && yarn install --ignore-engines

No yarn build step is needed — the babel plugin is installed from npm.

Commands

All commands run from xplat/js/RKJSModules/Libraries/Relay/oss/__github__/.

Run all e2e tests:

yarn test:e2e

Run a single fixture by name (use the path without extension, e.g. queries/greeting):

yarn test:e2e -- --testNamePattern greeting

Compiler resolution

The test harness resolves the relay-compiler binary in this order:

1. RELAY_COMPILER_BINARY env var 2. Local cargo build: compiler/target/debug/relay 3. npm fallback: node_modules/.bin/relay-compiler

To test compiler changes, build with cargo build --manifest-path=compiler/Cargo.toml --bin relay and re-run tests.

Writing Fixtures

Each test is a fixtures/<name>.md file. Fixtures can be organized into subdirectories (e.g. fixtures/errors/catch.md). The test name uses the relative path without extension (e.g. errors/catch). Snapshots are placed alongside the fixture as <name>.snap.md.

Every fixture needs three code blocks:

1. `relay.config.json` - Relay compiler configuration 2. `server.ts` - Grats schema and resolvers 3. `App.tsx` - React component that default-exports the test app

Each code block must include a title="<filename>" attribute on the code fence (e.g. ` `json title="relay.config.json" `). The title determines the output filename — the language tag is only for syntax highlighting.

Each code block should be preceded by a ## heading describing its contents (## Relay Config, ## Server, ## App, ## Steps). Additional files get their own descriptive heading (e.g. ## Counter Store). A short note can be added between the heading and the code block when something is non-obvious.

Keep server code (Grats types, resolvers, directives, server-side state) in server.ts and client code (React components, Relay environment/network setup) in App.tsx.

Example fixture

````markdown

Greeting Query

A basic test: Grats resolver returns a string, Relay fetches it, component renders it.

Relay Config

```json title="relay.config.json" { "src": "./", "schema": "./schema.graphql", "language": "typescript" }

## Server

/* @gqlQueryField / export function greeting(): string { return "Hello!"; }

## App

import { Suspense } from "react"; import { RelayEnvironmentProvider, useLazyLoadQuery } from "react-relay"; import { graphql, Environment } from "relay-runtime"; import { gratsNetwork } from "../GratsNetwork"; import { AppTestQuery } from "./__generated__/AppTestQuery.graphql";

const testEnvironment = new Environment({ network: gratsNetwork });

function Greeting() { const data = useLazyLoadQuery<AppTestQuery>( graphql query AppTestQuery { greeting } , {}, ); return <div>{data.greeting}</div>; }

export default function TestApp() { return ( <RelayEnvironmentProvider environment={testEnvironment}> <Suspense fallback={<div>Loading...</div>}> <Greeting /> </Suspense> </RelayEnvironmentProvider> ); }

## Steps

wait "Hello!"

Server code

Use Grats to define the server schema. @gqlQueryField / @gqlMutationField / @gqlSubscriptionField for resolvers. Prefer @gqlType on TypeScript type literals over classes:

/** @gqlType */
type User = {
  /** @gqlField */
  name: string;
};

Use classes only when needed (e.g. async method resolvers like async bio(): Promise<string>).

Import the shared network via import { gratsNetwork } from "../GratsNetwork". Import generated types from ./__generated__/.

Grats documentation is in the Grats package in node_modules:

Key files: getting-started.md, resolvers.md, docblock-tags.md

Interactions

Add a steps block to run user interactions before the snapshot is taken:

````markdown

wait button "Save"
click button "Save"
type textbox "Search" "hello"

````

Syntax: action [role] "name" ["value"]

Roles are ARIA roles (button, link, textbox, checkbox, etc.) as defined by Testing Library. Names must be quoted.

wait polls until a matching element appears (uses findByText/findByRole). Use it to wait for Suspense to resolve or for async data to arrive before snapshotting or interacting.

Snapshots

Run tests to generate snapshots. Delete a .snap.md file and re-run to regenerate. Console output (log/warn/error) is captured and included in the snapshot when present.

Relay docs

To understand how Relay APIs work, consult the Relay docs source files:

Key directories: api-reference/, guided-tour/, guides/, getting-started/