Debugging

This guide covers debugging tools, techniques, and troubleshooting for Rainbow Wallet development.

Development Tools

React DevTools

Inspect React component hierarchy, props, and state:

# Install globally
npm install -g react-devtools

# Run
react-devtools

Then:

Start your app (yarn ios or yarn android)
React DevTools will connect automatically
Inspect components, view props/state, profile performance

Flipper

Flipper is Facebook’s debugging platform for mobile apps:

Download from https://fbflipper.com/
Install and launch Flipper
Run your app (with Flipper support enabled - default)
App appears in Flipper automatically

Flipper Features:

Network Inspector - View all network requests/responses
React DevTools - Integrated React DevTools
Logs - View console logs and native logs
Layout Inspector - Inspect view hierarchy
Redux Inspector - Debug Redux state (if using Redux)
Crash Reporter - View crash logs

To build without Flipper (lighter builds): yarn install-pods-no-flipper

Metro Bundler Logs

Metro shows bundling progress and JavaScript errors:

# Standard output
yarn start

# With client logs (shows console.log)
yarn start:client-logs

# Clean cache and restart
yarn start:clean

Native Logs

iOS Logs

View iOS logs:

# React Native CLI
react-native log-ios

# Or in Xcode
# Open ios/Rainbow.xcworkspace
# Run app, then view logs in Xcode console (Cmd+Shift+Y)

Android Logs

View Android logs:

# React Native CLI
react-native log-android

# Or adb logcat
adb logcat

# Filter for React Native
adb logcat *:S ReactNative:V ReactNativeJS:V

# Or in Android Studio
# Open android/ folder, run app, view Logcat tab

Debugging Techniques

Console Logging

Basic debugging with console.log:

console.log('Debug value:', value);
console.warn('Warning:', warning);
console.error('Error:', error);

View logs:

Metro: yarn start:client-logs
Flipper: Logs plugin
Chrome DevTools: When remote debugging

Debugger Statement

Use debugger to set breakpoints:

function processData(data) {
  debugger; // Execution pauses here when debugging
  return data.map(item => item.value);
}

React DevTools Profiler

Profile component render performance:

Open React DevTools
Go to Profiler tab
Click Record
Interact with app
Click Stop
Analyze component render times

Network Debugging

Flipper Network Inspector

View all network requests in Flipper’s Network plugin.

React Native Debugger

Alternative to Chrome DevTools with Network tab:

# Install
brew install --cask react-native-debugger

# Run
open "rndebugger://set-debugger-loc?host=localhost&port=8081"

Redux DevTools

For debugging Redux state (Rainbow uses Redux for some legacy features):

Install Redux DevTools Extension
Use with React Native Debugger or Flipper Redux plugin

End-to-End (E2E) Testing

Rainbow uses Maestro for end-to-end testing.

Running E2E Tests

Enable testing mode

Set in your .env file:

IS_TESTING=true

Build in release mode

iOS
Android

yarn ios --mode Release

Or build from Xcode with Release configuration.

yarn android --mode Release

You can also run in development mode for easier debugging, but it may differ from CI.

Run tests

./scripts/e2e-run.sh

E2E Test Structure

Tests are in e2e/flows/ directory:

e2e/
├── flows/
│   ├── auth/
│   │   ├── ImportWallet.yaml
│   │   └── CreateWallet.yaml
│   └── utils/
│       └── ImportWalletWithKey.yaml
└── README.md

E2E Test Commands

Maestro uses deep links to speed up test setup:

# Deep link command
- openLink: rainbow://e2e/<command>?param1=value1&param2=value2

Commands are implemented in src/components/TestDeeplinkHandler.tsx.

Debugging E2E Tests

Cannot find view with testID on iOS

On iOS, testID uses accessibilityIdentifier. If a parent view has accessible=true, children’s testIDs are hidden.Solution: Move testID to the accessible parent or set accessible=false.

// ❌ Bad - won't work
<ButtonPressAnimation>
  <View testID="test" />
</ButtonPressAnimation>

// ✅ Good
<ButtonPressAnimation testID="test">
  <View />
</ButtonPressAnimation>

Long wait time between actions

Maestro waits for the app to “settle” (no animations). Looping animations prevent settling.Solution: Use IS_TEST from @/env to disable animations in tests:

import { IS_TEST } from '@/env';

const AnimatedComponent = () => {
  if (IS_TEST) return <StaticComponent />;
  return <AnimatedComponent />;
};

Flaky tests

Use Maestro’s retry mechanism:

- retry:
    maxRetries: 3
    commands:
      - tapOn: "Flaky Button"
      - assertVisible: "Expected Result"

CI E2E Tests

E2E tests run on CI for every PR. View logs in GitHub Actions artifacts:

Go to Actions run: https://github.com/rainbow-me/rainbow/actions/runs/<run_id>
Scroll to Artifacts
Download test logs

Performance Debugging

React Native Performance Monitor

Open developer menu (Cmd+D on iOS, Cmd+M on Android)
Enable Show Perf Monitor
View RAM, JavaScript FPS, UI FPS

Shopify Performance Monitoring

Rainbow uses @shopify/react-native-performance:

import { PerformanceProfiler } from '@shopify/react-native-performance';

<PerformanceProfiler>
  <App />
</PerformanceProfiler>

Check package.json for related performance scripts.

Memory Leaks

iOS Memory Profiling

Open Xcode
Product → Profile (Cmd+I)
Select Leaks or Allocations instrument
Run and interact with app
Analyze memory usage

Android Memory Profiling

Open Android Studio
Run app
View → Tool Windows → Profiler
Select app process
Click Memory timeline
Analyze memory allocations and GC events

Common Issues & Solutions

Metro bundler connection issues

Symptoms: “Unable to connect to development server”Solutions:

# Restart Metro with cache cleared
yarn clean:packager
yarn start --reset-cache

# For Android, reverse ports
yarn android-reverse-ports

White screen on launch

Symptoms: App shows white screen, no contentSolutions:

Check Metro bundler is running
View logs for JavaScript errors
Try reloading: Cmd+R (iOS) or R+R (Android)
Check .env file is configured
Rebuild app: yarn ios or yarn android

Native module errors

Symptoms: “Native module X is not available”Solutions:

# iOS: Reinstall pods
yarn clean:ios
yarn install-pods

# Android: Clean and rebuild
yarn clean:android
cd android && ./gradlew assembleDebug && cd ..

# Both: Full clean
./scripts/nuke.sh
yarn install && yarn setup

Slow performance in debug mode

Symptoms: App is very slow, animations lagCause: Debug builds are much slower than releaseSolutions:

Disable remote debugging (very slow)
Use release mode for performance testing: yarn ios --mode Release
Use Flipper or React DevTools instead of Chrome DevTools

Build succeeds but app crashes on launch

Symptoms: Build completes but app crashes immediatelySolutions:

View native crash logs (Xcode console or Android logcat)
Check for missing environment variables in .env
Verify native modules are linked correctly
Check for conflicting dependencies
Try clean rebuild

Hot reload not working

Symptoms: Changes don’t reflect in appSolutions:

Ensure Metro is running
Open developer menu, ensure Fast Refresh is enabled
Try manual reload: Cmd+R (iOS) or R+R (Android)
Restart Metro: yarn start --reset-cache
Some changes require full rebuild (native code, new dependencies)

Verification Commands

Run these before committing code:

# Type check TypeScript
yarn lint:ts

# Type check JavaScript (against baseline)
yarn lint:js-types

# ESLint
yarn lint:js

# All linting (format + TS + JS)
yarn lint

# Run tests
yarn test

# Run specific test
yarn jest path/to/test

# Check for circular dependencies
yarn check:cycles

CI Linting

CI runs additional checks:

yarn lint:ci

This runs:

yarn format:check - Prettier formatting
yarn lint:ts - TypeScript type checking
yarn lint:js:ci - ESLint (all files, not just changed)
yarn lint:js-types - JavaScript type checking against baseline

Debugging Best Practices

Use TypeScript - Catch errors at compile time
Write tests - Unit tests catch regressions early
Use ESLint - Enforce code quality and catch common mistakes
Check types - Run yarn lint:ts frequently
Profile performance - Use React DevTools Profiler for slow components
Monitor bundle size - Large bundles slow down app startup
Test on real devices - Simulators/emulators don’t represent real performance
Use release mode - For accurate performance testing
Check circular deps - Run yarn check:cycles to find circular dependencies
Read error messages - React Native error screens often have helpful stack traces

Introduction

Setup

Development

Development Tools

React DevTools

Flipper

Metro Bundler Logs

Native Logs

iOS Logs

Android Logs

Debugging Techniques

Console Logging

Debugger Statement

React DevTools Profiler

Network Debugging

Flipper Network Inspector

React Native Debugger

Redux DevTools

End-to-End (E2E) Testing

Running E2E Tests

E2E Test Structure

E2E Test Commands

Debugging E2E Tests

CI E2E Tests

Performance Debugging

React Native Performance Monitor

Shopify Performance Monitoring

Memory Leaks

iOS Memory Profiling

Android Memory Profiling

Common Issues & Solutions

Verification Commands

CI Linting

Debugging Best Practices

Additional Resources

Next Steps

Architecture

Running the App

Build docs developers (and LLMs) love

Introduction

Setup

Development

​Development Tools

​React DevTools

​Flipper

​Metro Bundler Logs

​Native Logs

​iOS Logs

​Android Logs

​Debugging Techniques

​Console Logging

​Debugger Statement

​React DevTools Profiler

​Network Debugging

​Flipper Network Inspector

​React Native Debugger

​Redux DevTools

​End-to-End (E2E) Testing

​Running E2E Tests

​E2E Test Structure

​E2E Test Commands

​Debugging E2E Tests

​CI E2E Tests

​Performance Debugging

​React Native Performance Monitor

​Shopify Performance Monitoring

​Memory Leaks

​iOS Memory Profiling

​Android Memory Profiling

​Common Issues & Solutions

​Verification Commands

​CI Linting

​Debugging Best Practices

​Additional Resources

​Next Steps

Architecture

Running the App

Build docs developers (and LLMs) love

Development Tools

React DevTools

Flipper

Metro Bundler Logs

Native Logs

iOS Logs

Android Logs

Debugging Techniques

Console Logging

Debugger Statement

React DevTools Profiler

Network Debugging

Flipper Network Inspector

React Native Debugger

Redux DevTools

End-to-End (E2E) Testing

Running E2E Tests

E2E Test Structure

E2E Test Commands

Debugging E2E Tests

CI E2E Tests

Performance Debugging

React Native Performance Monitor

Shopify Performance Monitoring

Memory Leaks

iOS Memory Profiling

Android Memory Profiling

Common Issues & Solutions

Verification Commands

CI Linting

Debugging Best Practices

Additional Resources

Next Steps