Skip to content

Commit 8c389bb

Browse files
authored
Document when to use Fantom instead of Jest for new tests
Summary: ## Context New tests for React Native runtime logic should be Fantom tests, but nothing says so. The repository guide lists Jest first as the unit test runner and only says Fantom runs as Android, the Fantom README only asks contributors to "consider" Fantom, and the review guidance accepts either runner "as fits the code". As a result, recent changes added new Jest test files, and new cases to Jest files that already have a Fantom sibling, for code Fantom can run. ## Changes - Fantom README: add a "Fantom or Jest?" section. Runtime logic (JavaScript that runs in apps using React Native, such as `Libraries` and `src`) gets Fantom tests, including new cases for modules that already have a Jest test. iOS-specific logic and code that runs in Node.js (build tools, scripts, Codegen, Babel and Metro configuration, the CLI, the dev server) use regular Jest. This is the only place the policy is written; the other files link to it. - `AGENTS.md`: point to that section before adding or extending a JavaScript test, and stop describing Jest as the default unit test runner. - Code review prompts: describe the test topology with the same split. Changelog: [Internal] Differential Revision: D132892213 Pull Request resolved: #60112
1 parent 23a196d commit 8c389bb

3 files changed

Lines changed: 24 additions & 7 deletions

File tree

‎.expo-code-review/shared.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,9 @@ and native-component specifications generate native counterparts. Treat the
3232
specification or configuration as the source of truth. Do not ask an author to
3333
hand-edit generated output, and do not report a filtered generated file as missing.
3434

35-
Use the repository's test topology to validate a suspected defect. Jest covers
36-
local JavaScript behavior. Fantom covers integrated runtime behavior. Android and
35+
Use the repository's test topology to validate a suspected defect. Fantom covers
36+
runtime logic, the JavaScript that runs in apps. Jest covers iOS-specific logic
37+
and code that runs in Node.js, such as build tools and scripts. Android and
3738
Apple have native build and test lanes. A missing test alone is not a warning;
3839
report the concrete behavior that fails.
3940

‎AGENTS.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,8 +30,8 @@ Architecture notes live in `__docs__` directories beside the code they describe,
3030

3131
| Command | Purpose |
3232
| --- | --- |
33-
| `yarn test <path>` | Jest unit tests, found in `__tests__` directories |
34-
| `yarn fantom <path>` | [Fantom](private/react-native-fantom/__docs__/README.md) integration tests, named `*-itest.js` — builds a native tester on first run, and runs as `Platform.OS === 'android'`, so an iOS-only branch needs Jest |
33+
| `yarn test <path>` | Jest tests, found in `__tests__` directories and named `*-test.js` |
34+
| `yarn fantom <path>` | [Fantom](private/react-native-fantom/__docs__/README.md) integration tests, named `*-itest.js` — builds a native tester on first run |
3535
| `yarn lint` | ESLint (`--max-warnings 0`) |
3636
| `yarn flow-check` | Flow |
3737
| `yarn format` | Format JavaScript/TypeScript, C/C++/Objective-C/protobuf, Kotlin, Java, Python, and Swift sources |
@@ -41,6 +41,8 @@ Architecture notes live in `__docs__` directories beside the code they describe,
4141

4242
JavaScript CI is the `lint`, `test_js`, and `build_js_types` jobs in [`.github/workflows/test-all.yml`](.github/workflows/test-all.yml); Fantom and the native platforms have their own jobs.
4343

44+
Before adding or extending a JavaScript test, read [Fantom or Jest?](private/react-native-fantom/__docs__/README.md#fantom-or-jest) to choose the test runner.
45+
4446
The formatting command uses pinned npm packages for Kotlin and Java and installs pinned Ruff through Python. To format every language, install a JDK with Java 17 or newer, Python 3 with pip, and a Swift 6.3 or newer toolchain in addition to Node and Yarn. Each language wrapper checks its own requirements and prints installation guidance when something is missing; `yarn format` then skips that language and continues formatting the others. Swift formatting accepts either `swift-format` or `swift format` from the installed toolchain.
4547

4648
## Gotchas

‎private/react-native-fantom/__docs__/README.md‎

Lines changed: 17 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -50,15 +50,29 @@ expect(boundingClientRect.width).toBe(100);
5050
```
5151

5252
Fantom is designed to make it possible to test the integration between
53-
JavaScript, React and React Native core - platform agnostic parts. When you are
54-
making a change to any of these parts, you should consider writing a Fantom test
55-
for it. It is geared towards engineers working on React Native.
53+
JavaScript, React and React Native core - platform agnostic parts. It is geared
54+
towards engineers working on React Native.
5655

5756
With Fantom you can create scenarios close to those how a real product will
5857
interact with React Native and observe what effects it has on a mock host
5958
platform. It exposes fine grained controls over scheduling, making it possible
6059
to test cases that are hard to reproduce manually.
6160

61+
## Fantom or Jest?
62+
63+
Use Fantom for new tests of React Native runtime logic: JavaScript that runs in
64+
apps using React Native, such as the code in `packages/react-native/Libraries`
65+
and `packages/react-native/src`. This includes new test cases for a module that
66+
already has a Jest test: add them to its Fantom test (or create one) instead of
67+
extending the Jest test.
68+
69+
Use regular Jest for:
70+
71+
- iOS-specific logic that needs a test, because Fantom runs as
72+
`Platform.OS === 'android'`.
73+
- Code that runs in Node.js rather than in apps, such as build tools, scripts,
74+
Codegen, the Babel and Metro configuration, the CLI and the dev server.
75+
6276
## 🚀 Usage
6377

6478
Create a file with the `-itest.js` suffix anywhere you would normally create a

0 commit comments

Comments
 (0)