Back to Details

validation-testing

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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.
对迁移后的代码进行全面的验证检查，确保正确性并排查常见的迁移问题。
NO MIGRATION IS COMPLETE WITHOUT A PASSING BUILD
“能编译”不代表“能正常运行”，“验证器通过”不代表“构建成功”。请执行以下每一个步骤。若迁移声称已完成但构建未通过，则不算真正完成。

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
本技能需要安装
nextjs-migration-toolkit
技能。所有迁移技能都依赖它进行AST分析。
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

1. 运行迁移验证器

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
bash
npx tsx "$TOOLKIT_DIR/src/bin/ast-tool.ts" validate <appDir>
该工具检查以下内容：
  • app/目录下的文件中无
    next/router
    导入（必须使用
    next/navigation
    ）
  • 无旧的数据获取导出（getStaticProps、getServerSideProps等）
  • 使用客户端特性的文件中缺少
    'use client'
    指令
  • 存在不符合App Router规范的孤立文件

2. Check Import Consistency

2. 检查导入一致性

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.
对于每个已迁移的文件：
bash
npx tsx "$TOOLKIT_DIR/src/bin/ast-tool.ts" transform imports <file> --dry-run
验证所有导入均使用与App Router兼容的模块。

3. Check Router Usage

3. 检查路由使用情况

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.).
对于每个已迁移的文件：
bash
npx tsx "$TOOLKIT_DIR/src/bin/ast-tool.ts" transform router <file>
验证是否残留有会导致错误的路由模式（router.query、router.pathname、router.events等）。

4. Verify Build

4. 验证构建

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
运行Next.js构建以排查编译错误：
bash
npx next build
迁移后常见的构建错误：
  • 因API变更导致的类型错误
  • 缺少导出内容（generateStaticParams、metadata）
  • 客户端/服务端边界冲突

5. Run Existing Tests

5. 运行现有测试

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
bash
npm test
若存在测试用例，请运行它们以验证行为是否保持一致。常见的测试失败原因：
  • 路由模拟需要更新（next/router → next/navigation）
  • 数据获取测试需要重构
  • 组件渲染测试可能需要处理
    'use client'
    指令

6. Manual Smoke Test Checklist

6. 手动冒烟测试清单

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
在浏览器中验证以下内容：
  • 所有路由可正常渲染且无错误
  • 页面间导航功能正常
  • 动态路由解析正确
  • 数据获取返回正确结果
  • 客户端交互功能正常（表单、按钮、模态框）
  • API路由响应正确
  • 图片加载正常
  • 元数据/SEO标签存在

7. Report Results

7. 报告结果

Generate a validation report summarizing:
  • Validator results (pass/fail per rule)
  • Build status
  • Test results
  • Remaining manual checks
Save to 
.migration/validation-report.md
.
生成一份验证报告，总结以下内容：
  • 验证器结果（每条规则的通过/失败情况）
  • 构建状态
  • 测试结果
  • 剩余的手动检查项
保存至
.migration/validation-report.md
。