Flipper Test Utilities

Common errors

• Cannot find module 'flipper-test-utils' or its corresponding type declarations.

  cause The package is not installed, or TypeScript cannot locate its declarations.
  fix Run `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

  cause This usually indicates an issue with CommonJS (`require`) trying to import an ESM-style named export, or incorrect named vs. default import.
  fix Ensure 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(...).

  cause 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.
  fix Wrap the code that causes state updates or re-renders (including the initial `render` call, user interactions, or awaiting async operations) within `await act(async () => { /* ... */ });`.

Warnings

• breaking As `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.
  Fix: Always 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`.
• gotcha When 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+.
  Fix: Import `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.
• 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.
  Fix: Ensure 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.

Install

• npm install flipper-test-utils npm
• yarn add flipper-test-utils yarn
• pnpm add flipper-test-utils pnpm

Imports

• render
  wrong:

  import { render } from '@testing-library/react';

  correct:

  import { render } from 'flipper-test-utils';

  While often wrapping `@testing-library/react`, `flipper-test-utils` exports its own `render` for Flipper-specific setup.
• createStubFlipperLib
  wrong:

  import { FlipperLib } from 'flipper-plugin'; // Then try to mock FlipperLib manually

  correct:

  import { createStubFlipperLib } from 'flipper-test-utils';

  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.

Quickstart

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();
  });
});