private/react-native-fantom/__docs__/README.md
[!WARNING]
This is experimental!
We are limiting the scope of the project to just React Native internals for now, so we can iterate on it quickly and keep the maintenance costs at bay.
In the future, we might explore providing it for testing library/product code internally and externally.
This means tests must live in
packages/react-native.
Fantom is the new integration testing and benchmarking tool for React Native.
Its main goal is to allow running JavaScript code as close as possible to a real React Native application, using its cross-platform architecture (Hermes, Fabric, C++ TurboModules, Bridgeless, etc.) in a fast headless environment that can run on CI.
Removing the need for real devices and simulators makes this faster and more stable than existing e2e testing solutions, while still allowing us to test the integration between JavaScript and native without the need for mocks.
When compared against Jest, layout is calculated and can be inspected in tests:
const root = Fantom.createRoot({viewportWidth: 200, viewportHeight: 600});
let viewElement;
Fantom.runTask(() => {
root.render(
<View
ref={node => {
viewElement = node;
}}
style={{width: '50%', height: '10%'}}
/>,
);
});
// Without Fantom, getBoundingClientRect would have to be mocked.
const boundingClientRect = viewElement.getBoundingClientRect();
expect(boundingClientRect.height).toBe(60);
expect(boundingClientRect.width).toBe(100);
Fantom is designed to make it possible to test the integration between JavaScript, React and React Native core - platform agnostic parts. When you are making a change to any of these parts, you should consider writing a Fantom test for it. It is geared towards engineers working on React Native.
With Fantom you can create scenarios close to those how a real product will interact with React Native and observe what effects it has on a mock host platform. It exposes fine grained controls over scheduling, making it possible to test cases that are hard to reproduce manually.
Create a file with the -itest.js suffix anywhere you would normally create a
Jest unit test file.
The high level structure of Fantom tests is similar to Jest unit tests. However,
only a subset of Jest's Global API is currently available. For example,
test.each is not yet implemented in Fantom. We are working on adding more Jest
APIs. If you are blocked by the lack of a specific API, please reach out to us.
Most of the interesting APIs are available via the @react-native/fantom
package:
import * as Fantom from '@react-native/fantom';
describe('My feature', () => {
it('should do something interesting', () => {
const root = Fantom.createRoot();
Fantom.runTask(() => {
root.render(/* ... */);
});
/* some checks */
});
});
For a full API reference, please see the inline documentation
defined for the methods in the @react-native/fantom module.
You can check out existing files with the -itest.js suffix (e.g.:
View-itest)
for code examples.
Run the test using the following command from the root of the React Native repository:
yarn fantom <regexForTestFiles>
Similar to Jest, you can also run Fantom in watch mode using --watch:
yarn fantom <regexForTestFiles> --watch
You can configure certain aspects of the test execution using pragmas in the docblock at the top of the file. E.g.:
/**
* @fantom_flags jsOnlyTestFlag:true
* @fantom_mode opt
*/
Available pragmas:
@fantom_flags: used to set overrides for
ReactNativeFeatureFlags.
@fantom_flags name:value.@fantom_flags name:value otherName:otherValue).@fantom_mode: used to define the compilation mode for the bundle.
@fantom_mode optdev: development, default for tests.opt: optimized and using Hermes bytecode, default for benchmarks.@fantom_native_opt: used to define the compilation mode for native code.
@fantom_native_opt truetrue: optimized native codefalse: development native code@fantom_js_opt: used to define the compilation mode for the JS bundle.
@fantom_js_opt truetrue: optimized JS bundlefalse: development JS bundle@fantom_js_bytecode: used to define if the JS bundle should use bytecode.
@fantom_js_bytecode truetrue: using Hermes bytecodefalse: not using Hermes bytecode@fantom_disable_coverage: used to disable coverage collection for the test.
@fantom_disable_coverage@fantom_react_fb_flags: used to set overrides for internal React flags set
in ReactNativeInternalFeatureFlags (Meta use only)Setting @fantom_mode is mutually exclusive with setting any of
@fantom_native_opt, @fantom_js_opt, and @fantom_js_bytecode.
For all pragmas, except non-boolean feature flags, you can use a wildcard (*)
as value to run the test with all possible values for that pragma. For example,
this test:
/**
* @fantom_flags jsOnlyTestFlag:*
* @fantom_mode *
*/
Would be executed with these combinations of options:
jsOnlyTestFlag | mode |
|---|---|
false | dev |
true | dev |
false | opt |
true | opt |
With an output such as:
Test (jsOnlyTestFlag š)
[...]
Test (jsOnlyTestFlag ā
)
[...]
Test (mode šš¢, jsOnlyTestFlag š)
[...]
Test (mode šš¢, jsOnlyTestFlag ā
)
[...]
Test (mode š, jsOnlyTestFlag š)
[...]
Test (mode š, jsOnlyTestFlag ā
)
[...]
[!WARNING] Meta-only: debugging only works on Meta's internal infrastructure at the moment.
You can use environment variables to enable debugging for your tests. These options can be combined to debug JS and C++ at the same time.
To debug JavaScript, run your fantom test with the flag FANTOM_DEBUG_JS:
FANTOM_DEBUG_JS=1 yarn fantom <regexForTestFiles>
This would open React Native DevTools, which would stop at a breakpoint at the beginning of your test so you can debug it.
To debug C++, run your fantom test with the flag FANTOM_DEBUG_CPP:
FANTOM_DEBUG_CPP=1 yarn fantom <regexForTestFiles>
This would start a debugging session in VS Code with an initial breakpoint in the Fantom CLI binary.
It's also possible to run the C++ side with the thread or address sanitizer enabled, which can help with debugging memory and threading issues.
To enable the address sanitizer, run your fantom test with the flag
FANTOM_ENABLE_ASAN:
FANTOM_ENABLE_ASAN=1 yarn fantom <regexForTestFiles>
For thread sanitizer, correspondingly, use flag FANTOM_ENABLE_TSAN:
FANTOM_ENABLE_TSAN=1 yarn fantom <regexForTestFiles>
You can automatically record JS sampling profiler traces with the flag
FANTOM_PROFILE_JS:
FANTOM_PROFILE_JS=1 yarn fantom <regexForTestFiles>
As part of the test results, you will see a message indicating where the traces where saved, e.g.:
š„ JS sampling profiler trace saved to /path/to/react-native/private/react-native-fantom/.out/js-traces/View-itest.js-2025-08-12T14:08:31.580Z.cpuprofile
If your test has multiple variants (when using wildcards in Fantom pragmas), a trace will be created for each variant.
You can analyze the traces loading them in Chrome DevTools directly. You can also open them in VS Code, which provides a built-in extension for analysis.
You can manually take JS memory heap snapshots during test execution using
Fantom.takeJSMemoryHeapSnapshot(). E.g.:
// Using the 3 snapshot method to detect memory leaks:
// Warm up
renderView();
destroyView();
// #1
Fantom.takeJSMemoryHeapSnapshot();
renderView();
// #2
Fantom.takeJSMemoryHeapSnapshot();
destroyView();
// #3
Fantom.takeJSMemoryHeapSnapshot();
// See the objects allocated between #1 and #2 that still exist in #3.
This function will force a garbage collection pass, take a snapshot of the JS memory heap and print a message indicating where it was saved. E.g.:
š¾ JS heap snapshot saved to /path/to/react-native/private/react-native-fantom/.out/js-heap-snapshots/View-itest.js-2025-08-12T14:29:25.987Z.heapsnapshot
You can have multiple calls to Fantom.takeJSMemoryHeapSnapshot() in your test,
and each one will create a different file.
Fantom runs C++ part of React Native, as well as JavaScript on Hermes VM - unlike Jest tests that run on V8. This makes it possible to test things related to shadow nodes, layout, events, scheduling, C++ state updates to name a few. The results of Fabric are mounted in a mock UI tree that can be asserted against and individual mounting instructions can be inspected.
You can even test your C++ code. For example, we have Fantom tests for the new View Culling optimization, which is written in C++.
Fantom exposes the method Fantom.scrollTo. This method will trigger an
onScroll event and configure the shadow tree to reflect the new content offset:
Fantom.scrollTo(scrollViewElement, {
x: 0,
y: 1,
});
expect(scrollViewElement.scrollTop).toBe(1);
Fantom was designed to make it possible to test integration between React and Fabric with the Jest API that many people are familiar with. You can write code to simulate any kind of input into React and assert what the output is from React Native core to the host platform. Fantom controls the app's message queue, which gives complete control over scheduling. This makes it possible to write tests that simulate scenarios where an event interrupts React rendering in a deterministic fashion.
Even JavaScript only code can be tested with Fantom. We are considering fully deprecating "vanilla" Jest in favor of Fantom for all JavaScript tests in React Native.
Fantom is a stable and reliable testing framework that is here to stay. If you're planning to make changes to React or React Native internals, we highly recommend using Fantom as your go-to testing solution.
Important Note: While Fantom is ideal for testing React and React Native internals, it is not currently supported for testing application-specific code in React Native apps. We'll keep you updated on any future developments that may change this.
Look for files with the -itest.js suffix to find existing tests. The Fantom
test for its public API (Fantom-itest.js)
has simple examples you can learn from.
Fantom tests are currently tied to Meta's infrastructure and do not run outside of Meta's CI. We are working on migrating Fantom to Github CI. If you submit a PR, the tests will run as part of the PR import process.
Yes, you can use the @fantom_flags pragma to customize the flags that are
going to be used for the entire test suite, and conditionally define or exclude
the test in the suite depending on the flag value for that run. E.g.:
/**
* @fantom_flags commonTestFlag:*
*/
import * as ReactNativeFeatureFlags from 'react-native/src/private/featureflags/ReactNativeFeatureFlags';
// The entire suite will be run with commonTestFlag set to true and false.
describe('MyTest', () => {
it('should run with all values of the flag', () => {
// ...
});
if (ReactNativeFeatureFlags.commonTestFlag()) {
it('should only run when the flag is true', () => {
// ...
});
}
if (!ReactNativeFeatureFlags.commonTestFlag()) {
it('should only run when the flag is false', () => {
// ...
});
}
});
And the result would look like this:
PASS MyTest-itest.js
MyTest (commonTestFlag ā)
ā should run with all values of the flag
ā should only run when the flag is false
MyTest (commonTestFlag ā
)
ā should run with all values of the flag
ā should only run when the flag is true
If you have any questions not answered here, please reach out to us.
Fantom tests are meant to be written, executed and reported as regular Jests tests. To accomplish that, Fantom is implemented as a Jest test runner.
Fantom provides a Jest configuration to use
its runner for any tests matching the -itest.js suffix
within the repository.
When Jest runs, for every file that matches that configuration, it calls into the Fantom runner, which receives the path to the test file along with different configuration objects.
The runner then follows these steps:
@fantom_flags pragmas defined in the docblock for test
files.