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
gh pr diff <pr-number> --repo Shopify/flash-list
gh pr view <pr-number> --repo Shopify/flash-list --comments

From a local branch

git log main..HEAD --oneline
git diff main...HEAD

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:

yarn test
yarn type-check
yarn lint

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:

git diff main...HEAD --name-only | grep 'fixture/react-native/'

# If matches found:
cd fixture/react-native && yarn build   # tsc -b — catches type errors in fixture code

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

# Check if e2e-relevant files were changed
git diff main...HEAD --name-only | grep -E '\.e2e\.|fixture/react-native/src/'

# If yes, run e2e tests on iOS
yarn e2e:ios

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:

cd fixture/react-native && yarn react-native run-ios

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.

yarn build   # runs tsc -b

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:

xcrun simctl get_app_container booted org.reactjs.native.example.FlatListPro 2>/dev/null

• 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:

cd fixture/react-native && yarn react-native run-ios

Relaunch the app

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

agent-device close --platform ios
xcrun simctl launch --terminate-running-process <UDID> org.reactjs.native.example.FlatListPro
agent-device open "FlatListPro" --platform ios

Find the simulator UDID with:

xcrun simctl list devices | grep Booted

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

yarn build
cd fixture/react-native && yarn react-native run-android

Navigate and verify

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

agent-device snapshot -i -c --json --session droid
agent-device press <x> <y> --session droid
agent-device screenshot /tmp/android-screen.png --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:

// Change this:
I18nManager.forceRTL(false);
// To this:
I18nManager.forceRTL(true);

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

agent-device close --platform ios
xcrun simctl launch --terminate-running-process <UDID> org.reactjs.native.example.FlatListPro
agent-device open "FlatListPro" --platform ios

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:

# Swipe right-to-left at y=30% (list center on HorizontalList screen)
agent-device swipe 350 256 50 256 --platform ios

Always revert RTL when done

I18nManager.forceRTL(false);

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:

# Terminal 1: start server
node -e "
const http=require('http'),fs=require('fs');
http.createServer((q,r)=>{
  if(q.method==='POST'){let b='';q.on('data',c=>b+=c);q.on('end',()=>{
    fs.appendFileSync('/tmp/rv-debug.log',b+'\n');console.log(b);r.end('ok');})}
  else r.end('ok');
}).listen(9876,()=>console.log('on :9876'));
"

Add to source (remember to remove after):

try {
  fetch("http://localhost:9876", {
    method: "POST",
    body: JSON.stringify({ tag: "myDebug", ...values }),
  }).catch(() => {});
} catch (e) {}

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