Validation & Testing

Run comprehensive validation checks on migrated code to ensure correctness and catch common migration issues.

NO MIGRATION IS COMPLETE WITHOUT A PASSING BUILD

"It compiles" is not "it works." "The validator passes" is not "the build succeeds." Run every step below. A migration claimed as complete without a passing build is not complete.

Toolkit Setup

This skill requires the nextjs-migration-toolkit skill to be installed. All migration skills depend on it for AST analysis.

TOOLKIT_DIR="$(cd "$(dirname "$SKILL_PATH")/../nextjs-migration-toolkit" && pwd)"
if [ ! -f "$TOOLKIT_DIR/package.json" ]; then
  echo "ERROR: nextjs-migration-toolkit is not installed." >&2
  echo "Run: npx skills add blazity/next-migration-skills -s nextjs-migration-toolkit" >&2
  echo "Then retry this skill." >&2
  exit 1
fi
bash "$TOOLKIT_DIR/scripts/setup.sh" >/dev/null

Steps

1. Run Migration Validator

npx tsx "$TOOLKIT_DIR/src/bin/ast-tool.ts" validate <appDir>

This checks for:

• No next/router imports in app/ files (must use next/navigation)
• No old data-fetching exports (getStaticProps, getServerSideProps, etc.)
• Missing 'use client' directives on files using client features
• Orphaned files not following App Router conventions

2. Check Import Consistency

For each migrated file:

npx tsx "$TOOLKIT_DIR/src/bin/ast-tool.ts" transform imports <file> --dry-run

Verify all imports use App Router-compatible modules.

3. Check Router Usage

For each migrated file:

npx tsx "$TOOLKIT_DIR/src/bin/ast-tool.ts" transform router <file>

Verify no breaking router patterns remain (router.query, router.pathname, router.events, etc.).

4. Verify Build

Run the Next.js build to catch compilation errors:

npx next build

Common build errors after migration:

• Type errors from changed APIs
• Missing exports (generateStaticParams, metadata)
• Client/server boundary violations

5. Run Existing Tests

npm test

If tests exist, run them to verify behavior is preserved. Common test failures:

• Router mocking needs updating (next/router → next/navigation)
• Data fetching tests need restructuring
• Component render tests may need 'use client' handling

6. Manual Smoke Test Checklist

Verify in the browser:

• All routes render without errors
• Navigation between pages works
• Dynamic routes resolve correctly
• Data fetching produces correct data
• Client-side interactions work (forms, buttons, modals)
• API routes respond correctly
• Images load properly
• Metadata/SEO tags are present

7. Report Results

Generate a validation report summarizing:

• Validator results (pass/fail per rule)
• Build status
• Test results
• Remaining manual checks

Save to .migration/validation-report.md.