review-and-test

Review & Test a FlashList PR or Branch

Prerequisites

which agent-device && which gh && yarn test --version

Ensure Metro is running from fixture/react-native/:

curl -s http://localhost:8081/status

Step 1 — Understand the Change

From a PR

gh pr view <pr-number> --repo Shopify/flash-list

From a local branch

Identify:

• What changed: which files, which functions
• Why: what bug is fixed or feature added
• Risk areas: layout, measurement, RTL, scroll, recycling

Step 2 — Run Automated Checks

All three must pass:

Fixture type-check (if fixture files changed)

Root yarn type-check only covers src/ — the fixture has a separate tsconfig.json. Root yarn lint does cover fixture files.

If any files in fixture/react-native/ were modified, also run:

E2E Tests

Run E2E tests if any of these changed in the PR/branch:

• E2E test files (*.e2e.*)
• Example/sample screens in fixture/react-native/src/
• New example screens added

E2E tests use Detox. The yarn e2e:ios script handles both build and test.

Warning: E2E builds a release app that replaces the debug app on the simulator. After running E2E, rebuild debug to continue interactive testing:

If tests fail, investigate before proceeding to device testing.

Step 3 — Build

CRITICAL: The fixture app uses compiled output from dist/. Source changes in src/ have NO effect until built.

Install the fixture app only if needed

Before building the native app, check if it's already installed on the simulator. Only build if it's not installed:

• If the command succeeds (returns a path): the app is installed. Skip run-ios — just relaunch it.
• If the command fails: the app is not installed. Build and install it:

Relaunch the app

After yarn build, relaunch the app (kill + reopen) so Metro serves the new bundle:

Find the simulator UDID with:

Step 4 — Test on Device (LTR)

Navigate to affected screens

Use the agent-device skill to navigate and take screenshots. Screens are listed on the Examples page. Common ones:

Smoke test

Navigate to each affected screen, scroll through content, verify no visual regressions.

Step 4b — Test on Android (if available)

If an Android emulator is available (e.g., on the android-agent CI runner), test there too. Android uses a native RecyclerView bridge so behavior can differ from iOS.

Build and install

Navigate and verify

Use agent-device with --platform android --session droid:

Android-specific things to check

• RecyclerView scroll behavior matches iOS
• Items render correctly (no blank/recycled artifacts)
• Sticky headers work with native scroll
• onEndReached / onStartReached fire at the same thresholds as iOS

Step 5 — Test RTL

How to enable RTL properly

The ONLY reliable method: change fixture/react-native/index.js:

Then kill and relaunch the app (a JS reload is NOT sufficient):

Do NOT use:

• DevSettings.reload() — does not properly apply RTL
• The Debug screen toggle — unreliable, layout may not fully flip

RTL verification checklist

• Text is right-aligned on the Examples screen
• Navigation back chevron is on the RIGHT side
• HorizontalList: items ordered right-to-left (Item 0 on right, higher items on left)
• HorizontalList: header is reachable by swiping right-to-left (toward the logical start)
• Grid: columns mirrored
• StickyHeaders: headers pin correctly
• Chat: messages align correctly
• Masonry: layout mirrors properly

RTL scrolling on horizontal lists

In RTL, the scroll direction is reversed:

• Swipe right-to-left (finger moves left): reveals content toward the logical START (header, Item 0)
• Swipe left-to-right (finger moves right): reveals content toward the logical END (higher items)

Use agent-device swipe with coordinates at the list center:

Always revert RTL when done

Step 6 — Verify firstItemOffset Values (for layout/measurement changes)

If the PR touches measureLayout, measureParentSize, firstItemOffset, or RecyclerView.tsx layout logic, verify the actual runtime values match expected values.

Expected values (verified on RN 0.84 Fabric)

How to capture runtime values

console.log does NOT work on Fabric/Hermes (output goes to CDP debugger, not Metro).

Use a local HTTP server instead:

Add to source (remember to remove after):

Then rebuild (yarn build), relaunch, navigate, and read /tmp/rv-debug.log.

measureParentSize x/y behavior

On RN 0.84 Fabric, view.measureLayout(view) returns x=0, y=0 (the Fabric self-measurement bug from #2017 does NOT reproduce on this version). The defensive fix that strips x/y is a no-op here but protects other RN versions.

Step 7 — Write Review Summary

After testing, provide:

1. Automated checks: pass/fail for test, type-check, lint
2. LTR behavior: which screens tested, any issues
3. RTL behavior: which screens tested, any issues
4. firstItemOffset verification (if applicable): actual vs expected values
5. Regression risk: low/medium/high with reasoning
6. Recommendation: approve, request changes, or needs more testing

Edge Cases to Test

Run through relevant entries after any fix or review. This is the single source of truth for edge case checklists — the fix-github-issue skill references this.

Layout & Measurement

• Content above FlashList (another component in the same parent View)
• ListHeaderComponent with variable height
• stickyHeaderOffset > 0 combined with content above FlashList
• Horizontal FlashList (x-axis equivalent of any vertical measurement bug)
• Horizontal list with wide ListHeaderComponent — header must be reachable by scrolling
• measureParentSize x/y values — on RN 0.84 Fabric these are (0,0), but on other RN versions they may be non-zero
• numColumns > 1 with ItemSeparatorComponent — last row items must have same height (no separator height mismatch)
• numColumns > 1 with ItemSeparatorComponent and overrideItemLayout (variable spans) — separator suppression must use layout y-coordinates, not index arithmetic

RTL (Right-to-Left)

• HorizontalList in RTL — items right-to-left, header reachable by swiping right-to-left
• Grid in RTL — column ordering reversed
• StickyHeaderExample in RTL — header must pin to correct edge
• Chat in RTL — messages align correctly
• Masonry in RTL

Sticky Headers

• Multiple sticky indices with content above FlashList (issue #2017 scenario)
• Sticky headers with stickyHeaderOffset > 0
• Sticky header transition at exact item boundary (scroll = item.y)
• Sticky header when next sticky is beyond engaged indices
• Sticky header + maintainVisibleContentPosition / startRenderingFromBottom
• hideRelatedCell: true — overlay hides original cell without jumping

New Architecture (Fabric)

• Any measureLayout/measureParentSize call — verify behaviour matches Paper
• firstItemOffset after fix — confirm it equals ListHeaderComponent height/width
• measureParentSize(view) returns x=0, y=0 on RN 0.84 Fabric — the #2017 bug may only manifest on other RN versions

Performance

• Benchmark screen shows no FPS regression (use ManualBenchmarkExample)

Common Issues

• Tests pass but device shows bug — did you yarn build and relaunch? The dist/ folder may be stale
• Switched branches but behavior didn't change — dist/ is NOT rebuilt on branch switch. You MUST run yarn build after every git checkout. Verify with grep in dist/ that the expected code is present before testing.
• RTL looks wrong but LTR is fine — did you set forceRTL(true) in index.js and do a full kill+relaunch?
• agent-device swipe gives "drag" error — delete ~/.agent-device/ios-runner/derived/ and re-run agent-device open to rebuild the iOS runner
• No console output in Metro — use the HTTP server approach (see Step 6)
• Metro log location — lsof -p $(lsof -ti :8081) | grep "1w" to find where Metro stdout goes (often /private/tmp/metro_fixture.log)
• RTL horizontal scroll direction is reversed — to scroll toward the logical START (header/Item 0), swipe right-to-left: agent-device swipe 350 256 50 256. To scroll toward higher items, swipe left-to-right.
• Fixture app bundle ID — org.reactjs.native.example.FlatListPro. Use with xcrun simctl launch.
• estimatedItemSize does not exist — this FlashList does NOT have this prop. Do not use it.
• App can't connect to Metro — if the app shows a red/yellow error about connecting to the bundler, configure the port: iOS simulator Cmd+D → "Configure Bundler" → set host localhost and the correct port. Then reload.
• agent-device navigation — use snapshot -i -c --json as the primary method for finding elements (returns exact coordinates). Fall back to screenshot + percentage-based press when elements aren't in the accessibility tree. See the agent-device skill for details.

Review Methodology

Always reproduce BEFORE verifying the fix

1. Checkout main, build (yarn build), relaunch, and reproduce the bug
2. Checkout the PR branch, build (yarn build), relaunch, and verify the fix
3. Verify dist after each branch switch: grep "expected_code" dist/path/to/file.js — if the old code is still there, the build didn't run or didn't pick up the change

Without step 1, you can't confirm the fix actually changed anything. Without verifying dist, you might test stale code on both branches and conclude "no difference" incorrectly.

Making behavior observable

When testing callback-based behavior (e.g., onStartReached, onEndReached, onViewableItemsChanged), add a visible counter to the fixture screen:

This gives immediate visual feedback in screenshots without needing console.log or debug servers.

Masonry PRs — watch for sorting

Any masonry layout PR that adds Array.sort() or sorted copies is a red flag for performance. getVisibleLayouts runs on every scroll frame (60fps). O(N log N) sorting per layout change is expensive. Items within each column are naturally sorted — per-column binary search is O(log N) without sorting.

Self-Evolving Instructions

This skill is the single source of truth for testing knowledge, edge cases, and debug techniques. The fix-github-issue skill delegates here for Steps 6-7.

After each session, update this file with:

1. New screens or scenarios that need testing
2. New debug techniques discovered
3. Updated expected values if the codebase changes
4. New edge cases discovered during fixes