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
skill to be installed. All migration skills depend on it for AST analysis.
bash
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
bash
npx tsx "$TOOLKIT_DIR/src/bin/ast-tool.ts" validate <appDir>
This checks for:
- No imports in app/ files (must use )
- No old data-fetching exports (getStaticProps, getServerSideProps, etc.)
- Missing directives on files using client features
- Orphaned files not following App Router conventions
2. Check Import Consistency
For each migrated file:
bash
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:
bash
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:
Common build errors after migration:
- Type errors from changed APIs
- Missing exports (generateStaticParams, metadata)
- Client/server boundary violations
5. Run Existing Tests
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 handling
6. Manual Smoke Test Checklist
Verify in the browser:
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
.