validation-testing

Original：🇺🇸 English
Translated

Use after migrating a route or completing a migration phase to verify correctness. Also use when the build breaks, tests fail, or you suspect migration regressions.

1installs
Sourceblazity/next-migration-skills
Added on

NPX Install

npx skill4agent add blazity/next-migration-skills validation-testing

Tags

Translated version includes tags in frontmatter
nextjs-migrationvalidation-testingapp-routerbuild-verificationmigration-checks

SKILL.md Content

View Translation Comparison →

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.
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 
    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:
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:
bash
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

bash
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
.