Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
render
✓ import { render } from 'flipper-test-utils';
✗ import { render } from '@testing-library/react';
While often wrapping `@testing-library/react`, `flipper-test-utils` exports its own `render` for Flipper-specific setup.
createStubFlipperLib
✓ import { createStubFlipperLib } from 'flipper-test-utils';
✗ import { FlipperLib } from 'flipper-plugin'; // Then try to mock FlipperLib manually
This utility is crucial for mocking the Flipper client API within your tests, providing a controlled environment for plugin interactions.
TestUtils
✓ import { TestUtils } from 'flipper-test-utils';
A general object containing various helpers and constants for Flipper tests, common in many testing libraries. Specific contents may vary by version.
act
✓ import { act } from 'react-dom/test-utils';
While not directly from `flipper-test-utils`, `act` is essential for React component testing to ensure updates are flushed and to avoid warnings.
Demonstrates how to render a Flipper plugin component and mock its Flipper client interactions for testing.
import React from 'react';
import { render, createStubFlipperLib } from 'flipper-test-utils';
import { act } from 'react-dom/test-utils'; // Essential for React 18+ tests
import { FlipperPlugin, Flipper } from 'flipper-plugin';
interface MyPluginClient {
getGreeting(): Promise<string>;
}
// Define a simple Flipper plugin component
class MyFlipperPlugin extends FlipperPlugin<any, any, any> {
static id = 'MyFlipperPlugin';
static title = 'My Flipper Plugin';
constructor(flipper: Flipper) {
super(flipper);
}
render() {
return (
<div>
<h1>Hello from My Flipper Plugin!</h1>
<GreetingFetcher client={this.client} />
</div>
);
}
}
// A component that uses the Flipper client
function GreetingFetcher({ client }: { client: MyPluginClient }) {
const [greeting, setGreeting] = React.useState('Loading...');
React.useEffect(() => {
const fetchGreeting = async () => {
const message = await client.getGreeting();
setGreeting(message);
};
fetchGreeting();
}, [client]);
return <p>{greeting}</p>;
}
describe('MyFlipperPlugin', () => {
it('renders correctly and fetches a greeting', async () => {
const stubFlipperLib = createStubFlipperLib();
// Mock the client's method directly on the stub
stubFlipperLib.pluginClient.getGreeting = async () => 'Hello World!';
let rendered;
await act(async () => {
rendered = render(
<MyFlipperPlugin flipper={stubFlipperLib} />,
{ wrapper: ({ children }) => <div>{children}</div> } // Provide a simple wrapper if needed
);
});
expect(rendered.getByText('Hello from My Flipper Plugin!')).toBeInTheDocument();
// Wait for the async effect to complete
await rendered.findByText('Hello World!');
expect(rendered.getByText('Hello World!')).toBeInTheDocument();
});
});
Debug
Known issues
breakingAs `flipper-test-utils` is deeply integrated into the Flipper monorepo, its APIs can experience breaking changes aligning with major or even minor Flipper desktop application updates. Referencing the main Flipper changelog is crucial for staying up-to-date, as this sub-package's dedicated changelog may not detail all related breaking changes.fixAlways test against the Flipper Desktop application version you target. Regularly consult the main Flipper CHANGELOG.md for migration guides and API adjustments, and update `flipper-test-utils` along with `flipper-plugin` and `flipper-common`.
affects: >=0.x
gotchaWhen testing React components that update state or use effects, ensure your test code that triggers these updates and assertions is wrapped in `act()`. Failure to do so can lead to `Act(...)` warnings and inconsistent test results, especially with React 18+.fixImport `act` from `react-dom/test-utils` and wrap your `render` calls, state updates, and assertions that trigger React lifecycle methods within `await act(async () => { /* ... */ });` blocks. affects: >=0.x (React Testing Library based)
gotcha`flipper-test-utils` assumes certain peer dependencies like `jest`, `@testing-library/react`, and `react`. While not always explicitly listed as direct dependencies in `package.json`, their absence or incompatible versions can lead to runtime errors during testing.fixEnsure that `jest`, `@testing-library/react`, `react`, and `react-dom` are installed as `devDependencies` in your project and are compatible with the version of `flipper-test-utils` you are using.
affects: >=0.x
Errors
Common errors & fixes
Cannot find module 'flipper-test-utils' or its corresponding type declarations.
The package is not installed, or TypeScript cannot locate its declarations.
fixRun `npm install flipper-test-utils` or `yarn add flipper-test-utils` to install it. Ensure your `tsconfig.json` includes `node_modules/@types` if using custom type roots.
TypeError: (0 , _flipper_test_utils.render) is not a function
This usually indicates an issue with CommonJS (`require`) trying to import an ESM-style named export, or incorrect named vs. default import.
fixEnsure you are using `import { render } from 'flipper-test-utils';` (ESM syntax) and that your test runner (e.g., Jest) is configured to handle ESM modules correctly. Avoid `const { render } = require('flipper-test-utils');` if the package primarily uses ESM named exports. Warning: An update to TestComponent inside a test was not wrapped in act(...).
A React component updated its state or props, causing a re-render outside of React's `act()` utility in your test. This can lead to unpredictable test behavior.
fixWrap the code that causes state updates or re-renders (including the initial `render` call, user interactions, or awaiting async operations) within `await act(async () => { /* ... */ });`. Audit
Dependencies
@testing-library/reactrequiredCore dependency for UI component testing, often re-exported or wrapped.
flipper-pluginrequiredProvides the Flipper Desktop plugin SDK and components, essential for plugin definition and API interaction.
flipper-commonrequiredSupplies shared utilities and types across Flipper packages.
reactrequiredFrontend library for building Flipper plugin UIs.