Local vs CI Test Consistency Setup

What Was Done

  1. Created .nvmrc file - Specifies Node v18 to match local Claude requirements
  2. Added quality check scripts to package.json:
    • npm run typecheck - Run TypeScript checks
    • npm run quality:check - Full CI simulation
    • npm run quality:check:fast - Quick lint + typecheck
    • npm run pre-push - Run before pushing code
  3. Created comprehensive documentation:
    • docs/development/LOCAL_CI_CONSISTENCY.md - Detailed guide
    • Updated docs/README.md - Added references
    • Updated CLAUDE.md - Added workflow instructions
  4. Created pre-push check script:
    • scripts/pre-push-check.sh - Simulates CI environment

Developer Workflow

Every Time You Start Working

nvm use  # Use Node v18

Before Committing

npm run quality:check:fast  # Quick check

Before Pushing

npm run pre-push  # Full CI simulation

If Tests Fail in CI

# 1. Check Node version
node --version  # Should be v18.x.x

# 2. Run in CI mode
CI=true npm run test:run

# 3. Check TypeScript
npm run typecheck

# 4. Full quality check
npm run quality:check

Key Fixes Applied

  1. Fixed selectedItems test - Removed non-existent properties, added proper types
  2. Added proper TypeScript types - AccessControl, null-safety checks
  3. Created consistency tooling - Scripts to match CI environment locally

Why Tests Fail in CI but Not Locally

  1. Node version - Must match between local and Docker (now both v18)
  2. TypeScript strictness - CI checks ALL files including tests
  3. CI environment - Different test runner settings
  4. Module resolution - Stricter in Docker build

Prevention

Always run npm run pre-push before pushing code!

Important Note

We standardized on Node v18 because:

  • Claude CLI requires Node v18
  • Docker now uses Node v18 to match
  • This eliminates version mismatch issues