flutter-test-to-jest
Port flutter_test files (unit `test()` and widget `testWidgets()`) from the poc_vedaxl test/ folder to Jest + @testing-library/react-native v14 in the workspace that owns the code, with fixtures, fake
SKILL.md.claude/skills/flutter-test-to-jest/SKILL.md
GitHubflutter_test → Jest + RNTL v14
The one rule that bites: in @testing-library/react-native v14, render returns a promise. Always await render(...) (and
await renderVida(...)). A missing await gives empty queries and act() warnings.
Where the test goes
Find the Dart test file in docs/migration/TRACEABILITY.md §e; it lists the Jest target(s). The rule (from CLAUDE.md):
test/<x>_test.dart → <workspace>/__tests__/<x camelCase>.test.ts(x) in the workspace that owns the code. Mixed files are split:
| Dart test content | Target |
|---|---|
fromJson / fixture parsing, repository requests over HTTP, ApiException handling |
packages/api/__tests__/<x>.test.ts |
Pure rules (checkout maths, bid validation, countdowns, route mapping, reward-wheel landing, PhotoRules, MemberState logic, validators) |
packages/core/__tests__/<x>.test.ts |
| ARB / translation / plural tests | packages/i18n/__tests__/<x>.test.ts |
| UI kit widgets | packages/ui/__tests__/<x>.test.tsx |
Screens, stores, services, navigation (testWidgets, ChangeNotifier state) |
apps/mobile/__tests__/<x>.test.tsx |
Start the file with // Ported from: test/<x>_test.dart. Keep the same group and test names (describe / test), in the same order,
so the Dart and Jest results can be compared one-to-one. If a case can't be ported (layout overflow, Hero), keep it as
test.skip('<same name>', …) with a one-line reason; don't silently drop it.
Procedure
- Read the Dart test file, its helpers (
helpers.dart,cart_fakes.dart,account_v3_helpers.dart) and the fixtures it loads. - Count
test(/testWidgets((grep -cE "^\s*(test|testWidgets)\(" file) so you can check you ported them all. - Port the fakes first (see below), then the tests group by group.
- Run
npm test -w <workspace> -- <file>; fix the code under test if the behaviour differs from Dart (the Dart test is the spec). - Update the §e row: status
testedwhen every case passes (or is skipped with a reason); note counts if the file was split.
Translating the pieces
API details and finder tables: references/flutter-test-api.md. The essentials:
testWidgets('empty orders show the shop button', (tester) async {
await pumpVida(tester, AccountSource(apis: fakeApis(orders: []), child: const OrdersPage()), state: signedIn());
await tester.pumpAndSettle();
expect(find.text('Start shopping'), findsOneWidget);
await tester.tap(find.text('Start shopping'));
expect(AppNav.tab.value, 1);
});
// Ported from: test/orders_v2_test.dart
test('empty orders show the shop button', async () => {
await renderVida(<OrdersPage />, { repositories: fakeApis({ orders: [] }), member: signedIn() });
expect(await screen.findByText('Start shopping')).toBeOnTheScreen();
fireEvent.press(screen.getByText('Start shopping'));
expect(navigationSpy.lastRoute()).toBe('products');
});
- Copy text assertions as they are (English by default). They check the copy, and the same i18n keys give the same strings.
pumpVida→renderVidainapps/mobile/__tests__/helpers/renderVida.tsx: wraps the real providers (QueryClient withretry: falseandgcTime: Infinity, i18n initialised with the real JSON in the requested locale,VidaOverlayProvider, the navigation container, the repositories context with fakes, initial store state). Reset Zustand stores between tests (store.setState(initial, true)inbeforeEach), like the Dart tests create a freshMemberState(ticking: false).pump()/pumpAndSettle()→await screen.findBy…,await waitFor(() => …), orawait act(async () => {}). With timers (countdowns, 10 s polling, 3.4 s splash, toasts):jest.useFakeTimers()andawait act(() => jest.advanceTimersByTimeAsync(ms)).tester.view.physicalSize = Size(990, 2340)+devicePixelRatio 2.75(= 360 dp wide): mockuseWindowDimensionsto{ width: 360, height: 851 }.expect(tester.takeException(), isNull)(no overflow) can't be checked in RN: assert that the screen renders and the long French strings are present.- Locales:
renderVida(ui, { locale: 'fr' }); for i18n package tests callinitI18n('fr').
Fakes and fixtures
- HTTP-level (repository tests):
fakeFetch()+fixture()frompackages/api/__tests__/helpers.ts; buildnew ApiClient({ baseUrl, fetch, getIdToken })and assertcalls[i].url / method / headers / body. DartMockClienthandlers become thereplycallback. - Repository-level (screen tests): Dart fakes subclass the repository (
class _FakeCart extends CartRepository). In TS, create an object typed as the repository (Pick<CartRepository, 'cart' | 'addItem'>or a class extending it withsuper(dummyClient)), returning parsed fixtures; record calls in arrays the test asserts on. Put shared fakes inapps/mobile/__tests__/helpers/(cartFakes.ts,accountFakes.ts), mirroringcart_fakes.dartandaccount_v3_helpers.dart. - Services (push, live auction updates, photo upload, auth): pass fakes through the same injection points as Dart
(
AuctionLiveUpdates,PhotoUploadService,AdminAccess({ readClaim, currentUid }),PushTokenSync({ account, tokens })), not module mocks. Native modules are already mocked globally inapps/mobile/jest.setup.js(gesture handler, AsyncStorage); add new global mocks there only for modules every test needs. - Fixtures are in
packages/api/__tests__/fixtures/*.json(36 files, byte-for-byte copies). Never edit them; if a test needs a variant, derive it in the test ({ ...fixture('v3_cart'), lines: [] }). - Streams (
StreamControllerfor Firestore /receivedpushes): a tiny emitter in the test (const emit = (v) => listeners.forEach(l => l(v))), wrapped inact().
Done when
- Every Dart
test/testWidgetshas a Jesttestwith the same name (ortest.skipwith a reason); counts match the §e row. -
await rendereverywhere; no act() warnings; fake timers restored (afterEach(() => jest.useRealTimers())). - Tests pass with
npm test -w <workspace>; the §e row is updated.