diff --git a/docs/dev-notes/2025-11-07/bump-vitest-from-v3.x-to-v4.x/plan.md b/docs/dev-notes/2025-11-07/bump-vitest-from-v3.x-to-v4.x/plan.md deleted file mode 100644 index 5dc187dba..000000000 --- a/docs/dev-notes/2025-11-07/bump-vitest-from-v3.x-to-v4.x/plan.md +++ /dev/null @@ -1,414 +0,0 @@ -# Vitest v3.2.4 → v4.0.7 アップデート計画 - -**作成日**: 2025-11-07 - -**対象バージョン**: v3.2.4 → v4.0.7 - -**ステータス**: ✅ 完了（2025-11-07） - -**優先度**: 中（Node バージョン要件引き上げのため必須） - -## 目次 - -1. [破壊的変更と影響](#破壊的変更と影響) -2. [推奨される新機能](#推奨される新機能) -3. [実装チェックリスト](#実装チェックリスト) -4. [リファレンス](#リファレンス) - ---- - -## 破壊的変更と影響 - -### 🔴 1. Node バージョン要件の引き上げ - **必須対応** - -| 項目 | v3.2.4 | v4.0.7 | -| --------- | ----------- | ------------------------------------ | -| Node 要件 | `>=18.16.0` | `^20.0.0 \|\| ^22.0.0 \|\| >=24.0.0` | -| 推奨 | Node 18系 | Node 20系以上 | - -**影響度**: ⚠️ 高（CI/ローカル環境両者に影響） - -**対処方法**: - -1. `package.json` の `engines.node` を `">=20.0.0"` に更新 -2. CI 環境（`.github/workflows/ci.yml`）は既に `node-version: 22` のため OK ✅ -3. ローカル開発環境を Node 20 系以上に統一 -4. Docker イメージを確認（現在 Node 22 使用） - -**修正例**: - -```json -{ - "engines": { - "node": ">=20.0.0", - "pnpm": "10.20.0" - } -} -``` - ---- - -### 🟡 2. カバレッジ設定の削除・変更 - **影響あり（ローカル開発）** - -**削除されたオプション**: - -- `coverage.all` -- `coverage.extensions` -- `coverage.ignoreEmptyLines` - -**影響**: ローカルで `pnpm coverage` 実行時にエラーになる可能性 - -**対処方法**: -`vite.config.ts` の `test.coverage` セクションを確認・更新 - -**修正例**: - -```typescript -// vite.config.ts -export default defineConfig({ - test: { - // ... その他設定 - coverage: { - provider: 'v8', - // ✅ 明示的に include を指定（未読込ファイルは集計対象外） - include: ['src/**/*.{ts,tsx,svelte}'], - // 除外パターンがあれば指定 - exclude: ['node_modules/**', '.svelte-kit/**', 'build/**'], - }, - }, -}); -``` - -**実行チェック**: - -```bash -# v4 に更新後、確認コマンド -pnpm coverage - -# 失敗した場合、coverage セクション全体を見直す -``` - ---- - -### 🟡 3. モック API の挙動変化 - **低～中（現プロジェクトでの利用は少ない）** - -**変更内容**: - -- `vi.restoreAllMocks()` は **spy のみ** 復元、automock は対象外に -- `vi.fn()` 由来のモックの履歴は `.mockReset()` / `.mockClear()` で手動制御 - -**影響**: テストで `vi.restoreAllMocks()` に頼っている場合 - -**対処方法**: 個別に明示的に制御 - -**修正例**: - -```typescript -// ❌ v3 スタイル（全て復元されない） -afterEach(() => { - vi.restoreAllMocks(); -}); - -// ✅ v4 スタイル（明示的に指定） -afterEach(() => { - vi.clearAllMocks(); // 呼び出し履歴をクリア - vi.resetAllMocks(); // 実装をリセット - vi.restoreAllMocks(); // spy のみ復元 -}); -``` - -**プロジェクト確認**: - -```bash -# 該当する usage を grep で確認 -grep -r "vi.restoreAllMocks\|vi.fn\|mockReset" src/ tests/ --include="*.ts" --include="*.svelte" -``` - -現状確認結果: `src/lib/example.test.ts` では基本的なテストのみのため影響なし - ---- - -### 🟡 4. クラス spy/mock の実装変更 - **低（今後の参考）** - -**変更内容**: クラス/コンストラクタを spy する場合、mock 実装は `function` キーワード或いは `class` で返すこと（アロー関数は `Not a constructor` エラー） - -**影響**: 今後 Prisma クライアント等をクラスとして mock する際に注意 - -**修正例（将来参考）**: - -```typescript -// ❌ v4 で失敗 -const spy = vi.spyOn(obj, 'Client').mockImplementation(() => ({ - method: () => 'result', -})); - -// ✅ v4 で OK（function キーワード） -const spy = vi.spyOn(obj, 'Client').mockImplementation(function () { - this.method = () => 'result'; -}); - -// ✅ v4 で OK（class キーワード） -const spy = vi.spyOn(obj, 'Client').mockImplementation( - class MockClient { - method() { - return 'result'; - } - }, -); -``` - ---- - -### 🟢 5. ワーカー/スレッド設定の統一 - **低（プロジェクトに影響なし）** - -**変更内容**: `poolOptions`, `maxThreads`, `maxForks` 等が廃止 → `maxWorkers` へ統一 - -**影響**: 本プロジェクトでは pool 設定未指定のため影響なし - ---- - -## 推奨される新機能 - -### ✅ 1. 改善されたワーカープール - -**内容**: tinypool 廃止し自作実装 → 並列実行の高速化・安定化 - -**メリット**: - -- テスト実行速度の向上（特に複雑な Svelte コンポーネント） -- メモリ使用率の改善 - -**活用**: デフォルト設定で自動的に効果あり - ---- - -### ✅ 2. V8 カバレッジの精度向上 - -**内容**: AST ベース再マッピング → 従来の誤検知を削減 - -**メリット**: - -- `pnpm coverage` レポートの信頼性向上 -- 未カバー行の正確な特定 - -**確認方法**: - -```bash -# v4 更新後、coverage レポートの数字が変わる可能性 -# → 一度レビューして新しい数字を基準に -pnpm coverage -``` - ---- - -### ✅ 3. `vi.spyOn()` / `vi.fn()` がコンストラクタ対応 - -**内容**: クラス や コンストラクタの mock がより直感的に - -**メリット**: - -- 依存注入テストが書きやすく -- 将来の Prisma クライアント mock 作成時に有用 - -**使用例（将来）**: - -```typescript -// 依存注入テストが簡潔に -const mockClient = vi.fn( - class MockPrismaClient { - user = { findUnique: vi.fn() }; - }, -); -``` - ---- - -## 実装チェックリスト - -### Phase 1: 準備・確認（0.5日） - -- [x] 現在の Vitest バージョンを確認 - ```bash - pnpm exec vitest --version - ``` -- [x] 既存テストスイートの基準を確立 - ```bash - pnpm test:unit - ``` -- [x] `vite.config.ts` の `test` セクション確認 - ```bash - grep -A 20 "test:" vite.config.ts - ``` -- [x] mock/spy 使用状況を確認 - ```bash - grep -r "vi\.\(fn\|spyOn\|restoreAllMocks\)" src/ tests/ --include="*.ts" - ``` -- [x] Node バージョン確認 - ```bash - node --version - ``` - -### Phase 2: マイグレーション実施（1日） - -- [x] `package.json` の `engines.node` を `">=20.0.0"` に更新 -- [x] vitest / `@vitest/coverage-v8` を v4.0.7 に更新 - ```bash - pnpm up -D vitest@4.0.7 @vitest/coverage-v8@4.0.7 - ``` -- [x] 依存を再インストール - ```bash - pnpm install - ``` -- [x] テストスイートを実行 - ```bash - pnpm test:unit - ``` -- [x] **実行時エラーが出たら以下を確認**: - - ✅ Coverage エラー → v4.0.7 では削除されたオプションは使用されていなかった - - ✅ Test エラー → 全テストがパス（1639 passed, 1 skipped） - -### Phase 3: Coverage 設定確認・修正（0.5日） - -**ローカル開発向けチェック**: - -- [x] `pnpm coverage` を実行 - ```bash - pnpm coverage - ``` -- [x] coverage レポートが正常に生成されることを確認 -- [x] `vite.config.ts` で `coverage.include` が明示されているか確認 -- [x] 必要に応じて `include` / `exclude` パターンを調整 - -**修正が必要な場合**: - -```bash -# vite.config.ts を編集 -vi vite.config.ts - -# 修正後、再実行 -pnpm coverage -``` - -### Phase 4: テスト動作確認（1日） - -- [x] CI でテストが正常に実行されることを確認 - ```bash - # ローカルで CI 相当の実行 - pnpm build && pnpm test:unit - ``` -- [x] 全テストがパス -- [x] エラーログを確認して必要な修正を実施 -- [x] 既存テスト結果と新テスト結果を比較 - -### Phase 5: ドキュメント更新（0.5日） - -- [x] このドキュメント（plan.md）の完了ステータスを更新 - ---- - -## リファレンス - -### 公式ドキュメント - -- [Vitest Migration Guide v4](https://vitest.dev/guide/migration.html#vitest-4) -- [Vitest v4.0.0 Release Notes](https://github.com/vitest-dev/vitest/releases/tag/v4.0.0) -- [Vitest Coverage Guide](https://vitest.dev/guide/coverage) - -### プロジェクト関連ファイル - -- `package.json` - 依存・Node 要件指定 -- `vite.config.ts` - Vitest 設定（test セクション） -- `.github/workflows/ci.yml` - CI パイプライン（Node 22 で既に OK） -- `.github/instructions/tests.instructions.md` - テスト戦略ガイド - -### コマンドリファレンス - -```bash -# バージョン確認 -pnpm exec vitest --version - -# テスト実行 -pnpm test:unit - -# カバレッジ実行（ローカル開発向け） -pnpm coverage - -# カバレッジレポート表示 -# → coverage/index.html をブラウザで開く - -# 特定ファイルのテストのみ実行 -pnpm test:unit src/lib/example.test.ts - -# Watch モード -pnpm test:unit --watch -``` - ---- - -## 補足事項 - -### 環境確認事項 - -**CI 環境**: Node 22 使用（`.github/workflows/ci.yml`）→ v4 要件満たす ✅ - -**ローカル開発**: Node バージョン確認が必須 - -```bash -node --version # v20.0.0 以上を推奨 -``` - -**Vite 互換性**: 本プロジェクトは Vitest の test 設定が `vite.config.ts` に内包 - -- `globals: true` → v4 で互換性あり（実行時確認推奨） -- `environment: 'jsdom'` → v4 で互換性あり（実行時確認推奨） - -### 実行時確認事項 - -Phase 1～2 で以下を実行して互換性確認: - -```bash -# 2 つの主要設定の動作確認 -pnpm test:unit -pnpm coverage -``` - -エラーが出た場合、出力メッセージの該当破壊的変更セクションを参照 - ---- - -## 実施結果・教訓 - -### ✅ 成功したポイント - -1. **破壊的変更への準備**: 計画段階で詳細に破壊的変更をドキュメント化しておいたため、実装時にスムーズに対応できた -2. **テストの安定性**: 既存テスト (1639 tests) が全てパスし、破壊的変更による影響が最小限だった - - `vi.restoreAllMocks()` の使用箇所も複数あったが、v4.0.7 では互換性を保つ設計になっていた -3. **Node バージョン**: 既に v22.17.0 を使用していたため、v4 の Node 要件 (>=20.0.0) をクリアしていた -4. **Coverage 設定**: v4.0.7 では削除されたオプション (`coverage.all`, `coverage.extensions`) が使用されていなかったため、追加の修正が不要だった - -### 🔍 実施時の注意点 - -1. **Package 更新時のオプション**: `pnpm up -D` で複数パッケージを同時更新する際は、`@vitest/ui` も忘れずに更新すること -2. **Coverage 設定の明示化**: v4.0.7 でもデフォルトで機能するが、`vite.config.ts` に `coverage` セクションを明示することでメンテナンス性が向上 -3. **テスト実行時間**: v3 と比べて v4 の方が若干高速化している（v3: 10.62s → v4: 10.01s） - -### 📌 今後の推奨事項 - -1. **Vitest v5 への準備**: 次のメジャーバージョンアップに向けて、公式の Migration Guide を定期的に確認 -2. **Mock/Spy の標準化**: v4 から推奨されている `function` キーワードまたは `class` キーワードを使った mock 実装を今後の新規テストで採用 -3. **CI/CD パイプラインの検証**: Node 20 以上の要件がある場合、CI の Node バージョン指定が最新の推奨値を反映しているか確認 - -### 📊 実施統計 - -| 項目 | v3.2.4 | v4.0.7 | 変化 | -| ---------------- | ----------- | ----------- | ------------- | -| テストファイル数 | 28 | 28 | 変化なし | -| テスト総数 | 1640 (pass) | 1640 (pass) | 100% パス継続 | -| 実行時間 | ~10.62s | ~10.01s | ↓ 6% 高速化 | -| Node 要件 | >=18.16.0 | >=20.0.0 | 引き上げ | - ---- - -**最終更新**: 2025-11-07 - -**ステータス**: ✅ アップデート完了 diff --git a/docs/dev-notes/2026-01-19/bump-zod-and-sveltekit-superforms/plan.md b/docs/dev-notes/2026-01-19/bump-zod-and-sveltekit-superforms/plan.md deleted file mode 100644 index 9c90e51f5..000000000 --- a/docs/dev-notes/2026-01-19/bump-zod-and-sveltekit-superforms/plan.md +++ /dev/null @@ -1,553 +0,0 @@ -# Zod 3.25.76 → 4.3.5 / sveltekit-superforms 2.27.4 → 2.29.1 アップデート計画 - -**作成日**: 2026-01-19 - -**対象バージョン**: - -- Zod: 3.25.76 → 4.3.5（メジャーバージョンアップ） -- sveltekit-superforms: 2.27.4 → 2.29.1（マイナーバージョンアップ） - -**ステータス**: ✅ 実装完了（デプロイ待ち） - ---- - -## 目次 - -1. [背景](#背景) -2. [破壊的変更と影響](#破壊的変更と影響) -3. [実装戦略](#実装戦略) -4. [実装タスク](#実装タスク) -5. [テスト戦略](#テスト戦略) -6. [検証チェックリスト](#検証チェックリスト) -7. [参考資料](#参考資料) - ---- - -## 背景 - -Zod 4 のリリース（2025年度後半）に伴い、sveltekit-superforms の対応化を検討。Zod 3 から 4 への移行は複数の破壊的変更が含まれるため、段階的なアップグレードを計画。 - -**期間**: 2025-06-04（Zod 4.0.0）～ 2026-01-19（最新版確認） - -**対象**: - -- `zod@3.25.76` → `zod@4.3.5` -- `sveltekit-superforms@2.27.4` → `sveltekit-superforms@2.29.1` - ---- - -## 破壊的変更と影響 - -### 🔴 1. エラーカスタマイズ API の統一 - **HIGH IMPACT** - -| 項目 | Zod 3 | Zod 4 | -| ---------- | --------------------------------------- | ------------------------- | -| API形式 | `{ message: '...' }` | `{ error: '...' }` | -| 削除機能 | `invalid_type_error` / `required_error` | 代替なし（`error`に統一） | -| `errorMap` | 名称変更なし | `error` に名称変更 | - -**プロジェクトへの影響**: - -- **ファイル数**: 1 ファイル（[src/lib/zod/schema.ts](src/lib/zod/schema.ts)） -- **変更箇所**: 15+ 箇所のエラーメッセージ定義 -- **影響スキーマ**: `authSchema`, `accountSchema`, `accountTransferSchema`, `workBookSchema`, `workBookTaskSchema` - -**実装例**: - -```typescript -// ❌ Zod 3 -z.string().min(3, { message: '3文字以上入力してください' }); - -// ✅ Zod 4 -z.string().min(3, { error: '3文字以上入力してください' }); -``` - -**対応方針**: 全て `{ error: '...' }` に統一（自動置換可能） - ---- - -### 🔴 2. FormData parsing での default 値挙動変更 - **MEDIUM-HIGH IMPACT** - -| パターン | Zod 3 | Zod 4 | -| ------------------------------------------------------------------ | --------------------------- | ------------------------------------------------------ | -| `z.object({ a: z.string().default('tuna').optional() }).parse({})` | `{}` | `{ a: 'tuna' }` | -| FormData で `urlSlug: ""` 送信 | 空文字が `undefined` に変換 | `.transform()` で `undefined` に変換（default 非適用） | - -**プロジェクトへの影響**: - -- **問題**: `urlSlug` フィールドの空文字列処理 -- **現在の実装**: [src/lib/zod/schema.ts:75-89](src/lib/zod/schema.ts#L75-L89) で `.transform()` で `""` → `undefined` に変換 -- **テスト**: [src/test/lib/zod/workbook_schema.test.ts](src/test/lib/zod/workbook_schema.test.ts) に以下テストあり: - - ✅ `when an url slug is given an empty string` (line 123) - - ✅ `when an url slug is given null` (line 133) - - ✅ `when an url slug is given undefined` (line 143) - -**対応方針**: テストの期待値確認 + `.transform()` 実装の継続 - ---- - -### 🟡 3. z.nativeEnum() の deprecation - **LOW-MEDIUM IMPACT** - -| 変更内容 | -| ------------------------------------------------------ | -| `z.nativeEnum(WorkBookType)` → `z.enum()` への移行推奨 | - -**プロジェクトへの影響**: - -- **使用箇所**: [src/lib/zod/schema.ts:72](src/lib/zod/schema.ts#L72) -- **機能**: `workBookType: z.nativeEnum(WorkBookType)` として使用 -- **動作**: Zod 4 でも機能するが、deprecated 警告が出る可能性 - -**対応方針**: 互換性維持（移行は v5 以降） - ---- - -### 🟡 4. エラーマップ優先順位の変更 - **LOW-MEDIUM IMPACT** - -| バージョン | 優先度 | -| ---------- | ------------------------------------------ | -| Zod 3 | `.parse()` のエラーマップ > スキーマレベル | -| Zod 4 | スキーマレベル > `.parse()` のエラーマップ | - -**プロジェクトへの影響**: - -- sveltekit-superforms が国際化エラーメッセージを処理している場合に影響 -- 現在: **日本語のみ** → 国際化対応なし → **影響なし** - -**対応方針**: 現時点では対応不要 - ---- - -### 🟢 5. 新機能: z.fromJSONSchema(), z.xor(), z.looseRecord(), .exactOptional() - **LOW IMPACT** - -| 機能 | 用途 | -| -------------------- | ------------------------------------------ | -| `z.fromJSONSchema()` | OpenAPI/JSON Schema から自動生成 | -| `z.xor()` | 排他的 union（今後活用可能） | -| `z.looseRecord()` | 部分的バリデーション（今後活用可能） | -| `.exactOptional()` | 厳密オプショナル（`urlSlug` など活用可能） | - -**対応方針**: アップグレード後に活用検討 - ---- - -## 実装戦略 - -### 段階的アップグレード（保守的アプローチ） - -``` -Phase 1: 事前準備 - ↓ -Phase 2: Zod 4 アップグレード + コード修正 - ↓ - [単体テスト実行] ← テスト: ユニットテストのみ - ↓ -Phase 3: sveltekit-superforms アップグレード + adapter 切り替え - ↓ - [統合テスト実行] ← テスト: ユニット + E2E テスト - ↓ -Phase 4: ローカル検証・デプロイ確認 -``` - -**メリット**: - -- 🔍 各フェーズの問題を切り分けやすい -- 📊 Zod の破壊的変更が明確に検出される -- ⚙️ adapter の互換性を確認してから切り替え - ---- - -## 実装タスク - -### 📋 Phase 1: 事前準備 - -- [x] スキーマ全体のバックアップ確認 - - 確認ファイル: [src/lib/zod/schema.ts](src/lib/zod/schema.ts) - - エラーメッセージ数: 15+ - -- [x] FormData パース時の挙動テスト - - テスト確認: [src/test/lib/zod/workbook_schema.test.ts](src/test/lib/zod/workbook_schema.test.ts) - - 特にチェック: `urlSlug` の `""` / `null` / `undefined` テスト - ---- - -### 📋 Phase 2: Zod 4 アップグレード - -#### Step 2.1: パッケージアップグレード - -- [x] `package.json` 更新 - - `zod@3.25.76` → `zod@4.3.5` に変更 - - 変更ファイル: [package.json](package.json) - -- [x] 依存関係インストール - - ```bash - pnpm install - ``` - - - 互換性エラー確認 - - `sveltekit-superforms@2.27.4` との互換性確認（まだ `zod` adapter は使用） - -- [x] ビルド動作確認 - - ```bash - pnpm build - ``` - - - エラー確認 - - 型チェック確認 - -#### Step 2.2: スキーマコード修正 - -- [x] [src/lib/zod/schema.ts](src/lib/zod/schema.ts) のエラーメッセージ API 統一 - - `{ message: '...' }` → `{ error: '...' }` に統一 - - 対象: 全15+箇所 - - `authSchema` の `.min()` / `.max()` / `.regex()` (5 箇所) - - `accountSchema` の `.min()` / `.max()` / `.regex()` (3 箇所) - - `accountTransferSchema` の `.refine()` (1 箇所) - - `workBookTaskSchema` の `.max()` (1 箇所) - - `workBookSchema` の `.min()` / `.max()` / `.refine()` (6 箇所) - -**修正例**: - -```typescript -// Before (Zod 3) -z.string().min(3, { message: '3文字以上入力してください' }); - -// After (Zod 4) -z.string().min(3, { error: '3文字以上入力してください' }); -``` - -#### Step 2.3: TypeScript 型チェック - -- [x] TypeScript エラー確認 - - ```bash - pnpm check - ``` - - - 型推論エラー確認 - - 必要に応じた型修正 - ---- - -### 📋 Phase 3: sveltekit-superforms アップグレード - -#### Step 3.1: パッケージアップグレード - -- [x] `package.json` 更新 - - `sveltekit-superforms@2.27.4` → `sveltekit-superforms@2.29.1` に変更 - - 変更ファイル: [package.json](package.json#L60) - -- [x] 依存関係インストール - - ```bash - pnpm install - ``` - - - 互換性エラー確認 - - Zod 4 との互換性確認 - -- [x] ビルド動作確認 - - ```bash - pnpm build - ``` - - - エラー確認 - -#### Step 3.2: Adapter 切り替え - -- [x] Adapter の `zod()` → `zod4()` 切り替え - - **対象ファイル**: 3 ファイル、計 6 箇所 - - **ファイル 1**: [src/routes/workbooks/create/+page.server.ts](src/routes/workbooks/create/+page.server.ts) - - ```typescript - // Before (Line 3, 27, 55) - import { zod } from 'sveltekit-superforms/adapters'; - ... - const form = await superValidate(null, zod(workBookSchema)); - const form = await superValidate(request, zod(workBookSchema)); - - // After - import { zod4 } from 'sveltekit-superforms/adapters'; - ... - const form = await superValidate(null, zod4(workBookSchema)); - const form = await superValidate(request, zod4(workBookSchema)); - ``` - - **ファイル 2**: [src/routes/workbooks/edit/[slug]/+page.server.ts](src/routes/workbooks/edit/[slug]/+page.server.ts) - - ```typescript - // Before (Line 3, 24, 28) - import { zod } from 'sveltekit-superforms/adapters'; - ... - const form = await superValidate(null, zod(workBookSchema)); - const form = await superValidate(request, zod(workBookSchema)); - - // After - import { zod4 } from 'sveltekit-superforms/adapters'; - ... - const form = await superValidate(null, zod4(workBookSchema)); - const form = await superValidate(request, zod4(workBookSchema)); - ``` - - **ファイル 3**: [src/routes/(admin)/account_transfer/+page.server.ts]() - - ```typescript - // Before (Line 5, 32, 49) - import { zod } from 'sveltekit-superforms/adapters'; - ... - const form = await superValidate(null, zod(accountTransferSchema)); - const form = await superValidate(request, zod(accountTransferSchema)); - - // After - import { zod4 } from 'sveltekit-superforms/adapters'; - ... - const form = await superValidate(null, zod4(accountTransferSchema)); - const form = await superValidate(request, zod4(accountTransferSchema)); - ``` - -- [x] TypeScript 型チェック - - ```bash - pnpm check - ``` - - - 型推論エラー確認 - ---- - -## テスト戦略 - -### 📋 Phase 4: テスト実行（段階的） - -#### Step 4.1: Phase 2 後のテスト（Zod 4 のみ） - -- [x] ユニットテスト実行 - - ```bash - pnpm test:unit - ``` - - - **目的**: Zod 4 のスキーマテスト確認 - - **対象テスト**: - - [src/test/lib/zod/workbook_schema.test.ts](src/test/lib/zod/workbook_schema.test.ts) (63 tests) - - [src/test/lib/zod/auth_schema.test.ts](src/test/lib/zod/auth_schema.test.ts) - - [src/test/lib/zod/account_transfer_schema.test.ts](src/test/lib/zod/account_transfer_schema.test.ts) - - **特に確認**: `urlSlug` の `""` / `null` / `undefined` 挙動 - - **期待**: ✅ 全テスト合格（テスト修正不要の可能性が高い） - -#### Step 4.2: Phase 3 後のテスト（Zod 4 + superforms 2.29.1） - -- [x] ユニットテスト再実行 - - ```bash - pnpm test:unit - ``` - - - **目的**: adapter 切り替え後のスキーマテスト再確認 - - **期待**: ✅ 全テスト合格 - -- [x] E2E テスト実行 - - ```bash - pnpm test:integration - ``` - - - **目的**: フロントエンド・フォーム送信の実装確認 - - **対象テスト**: - - `tests/signin.test.ts` - ログイン・ログアウト - - `tests/toppage.test.ts` - トップページ - - その他 E2E テスト - - **特に確認**: 問題集作成・編集フロー - - **期待**: ✅ 全テスト合格 - -#### Step 4.3: フルテストスイート - -- [x] 統合テスト実行 - - ```bash - pnpm test - ``` - - - **目的**: 全テストの最終確認 - - **構成**: `pnpm test:integration && pnpm test:unit` - - **期待**: ✅ 全テスト合格 - ---- - -### 📋 Phase 5: ローカル検証・デプロイ確認 - -#### Step 5.1: ローカル環境確認 - -- [x] ローカル dev 環境起動 - - ```bash - pnpm dev - ``` - - - **確認項目**: - - サーバー起動時エラー確認 - - ホットリロード動作確認 - - ブラウザコンソールエラー確認 - -- [x] UI 検証 - - 問題集作成画面にアクセス - - フォーム送信（有効な入力値） - - エラーメッセージ表示（無効な入力値） - - 日本語エラーメッセージが表示されることを確認 - -- [x] ユーザー名が 3 文字未満の場合 - ``` - 入力: "ab" - 期待: "3文字以上入力してください" (Zod 4の { error } で表示) - ``` - -#### Step 5.2: コード品質確認 - -- [x] TypeScript チェック - - ```bash - pnpm check - ``` - - - 型エラー確認 - -- [x] Lint / Format - - ```bash - pnpm lint - pnpm format - ``` - - - コード品質確認 - -#### Step 5.3: デプロイ確認 - -- [ ] Vercel preview デプロイ - - GitHub Actions で CI/CD パイプライン確認 - - 自動デプロイが成功することを確認 - - Preview URL でブラウザ検証 - -- [ ] 本番環境への merge - - Main ブランチへの merge - - 本番デプロイ確認 - ---- - -## 検証チェックリスト - -| 項目 | ステータス | 備考 | -| ------------------------------------- | --------------- | ------------ | -| 破壊的変更分析 | ✅ 完了 | Phase 1 完了 | -| Zod パッケージアップグレード | ✅ 完了 | Phase 2.1 | -| Zod スキーマ修正 | ✅ 完了 | Phase 2.2 | -| Zod ユニットテスト | ✅ 完了 | Phase 4.1 | -| sveltekit-superforms アップグレード | ✅ 完了 | Phase 3.1 | -| adapter 切り替え（zod → zod4） | ✅ 完了 | Phase 3.2 | -| ユニットテスト再実行 | ✅ 完了 | Phase 4.2 | -| E2E テスト実行 | ✅ 完了 | Phase 4.3 | -| ローカル dev 起動 | ✅ 完了 | Phase 5.1 | -| 日本語エラーメッセージ表示確認 | ✅ 完了 | Phase 5.2 | -| TypeScript チェック | ✅ 完了 | Phase 5.3 | -| Lint / Format | ✅ 完了 | Phase 5.4 | -| 共有 util ファイルの adapter 切り替え | ✅ 完了 | Phase 3.2.1 | -| テストモック設定の同期更新 | ✅ 完了 | Phase 4.2 | -| Vercel preview デプロイ | ⏳ 次のステップ | Phase 5.5 | -| 本番環境デプロイ | ⏳ 次のステップ | Phase 5.6 | - ---- - -## 参考資料 - -### Zod 公式ドキュメント - -- [Zod v4 Migration Guide](https://zod.dev/v4/changelog) -- [Zod v4 Release Notes](https://zod.dev/v4) -- [Zod v4 Basic Usage](https://zod.dev/basics) - -### sveltekit-superforms ドキュメント - -- [sveltekit-superforms Releases](https://github.com/ciscoheat/sveltekit-superforms/releases) -- [v2.28.0 - Zod 4 adapter 追加](https://github.com/ciscoheat/sveltekit-superforms/releases/tag/v2.28.0) -- [v2.29.1 - Latest fixes](https://github.com/ciscoheat/sveltekit-superforms/releases/tag/v2.29.1) -- [Superforms Documentation](https://superforms.rocks/) - -### プロジェクト関連ファイル - -- **スキーマ定義**: [src/lib/zod/schema.ts](src/lib/zod/schema.ts) -- **スキーマテスト**: - - [src/test/lib/zod/workbook_schema.test.ts](src/test/lib/zod/workbook_schema.test.ts) - - [src/test/lib/zod/auth_schema.test.ts](src/test/lib/zod/auth_schema.test.ts) - - [src/test/lib/zod/account_transfer_schema.test.ts](src/test/lib/zod/account_transfer_schema.test.ts) -- **実装ファイル**: - - [src/routes/workbooks/create/+page.server.ts](src/routes/workbooks/create/+page.server.ts) - - [src/routes/workbooks/edit/[slug]/+page.server.ts](src/routes/workbooks/edit/[slug]/+page.server.ts) - - [src/routes/(admin)/account_transfer/+page.server.ts]() - -### CI/CD - -- **テスト実行**: `pnpm test:unit` (vitest), `pnpm test:integration` (playwright) -- **デプロイ**: GitHub Actions → Vercel -- **環境**: Node.js 20+, pnpm 10.28.0 - ---- - -## 実装完了 - -**実行日時**: 2026-01-19 12:00 - 12:20（約20分） - -**実行者**: GitHub Copilot（自動実装） - -**テスト結果**: - -- ユニットテスト: **1757 passed | 1 skipped** ✅ -- E2E テスト: **18 passed | 1 skipped** ✅ -- Lint/Format: **35 warnings（既存） | 0 新規エラー** ✅ - -**変更ファイル一覧**: - -1. `package.json`: Zod 3.25.76 → 4.3.5、sveltekit-superforms 2.27.4 → 2.29.1 -2. `src/lib/zod/schema.ts`: 20 箇所の `{ message }` → `{ error }` に統一 -3. `src/routes/workbooks/create/+page.server.ts`: `zod` → `zod4` adapter 切り替え -4. `src/routes/workbooks/edit/[slug]/+page.server.ts`: `zod` → `zod4` adapter 切り替え -5. `src/routes/(admin)/account_transfer/+page.server.ts`: `zod` → `zod4` adapter 切り替え -6. `src/lib/utils/auth_forms.ts`: `zod` → `zod4` adapter 切り替え -7. `src/test/lib/utils/auth_forms.test.ts`: モック設定の `zod` → `zod4` 更新 - ---- - -## 教訓 - -### 1. **段階的アップグレードの重要性** - -- Zod 3 → 4 のメジャーバージョンアップを、Phase 分割で対応することで、各フェーズの問題を明確に切り分けられた -- スキーマテスト → adapter 切り替え → E2E テストという段階的検証が効果的 - -### 2. **共有ユーティリティ内の adapter 切り替え漏れ** - -- `auth_forms.ts` のような共有コードの `zod()` → `zod4()` 置換を見落とさないことが重要 -- grep で全プロジェクトをスキャンして、adapter の全使用箇所を確認 - -### 3. **テストモック設定の同期更新** - -- API 変更に伴い、テストの `vi.mock()` 定義も更新する必要がある -- `zod` export → `zod4` export の変更で、テスト実行時のエラーを防止 - -### 4. **エラーメッセージ API の統一** - -- `{ message }` → `{ error }` への置換は全スキーマで一貫性が必要 -- 正規表現検索で全置換箇所を検出可能 - -### 5. **ユニット + E2E テストの双方実施** - -- adapter 切り替え後、ユニットテストと E2E テストの両方を実行してバックエンド・フロントエンド互換性を確認 -- テスト全 pass で本番環境への信頼度が向上 - -### 6. **コード品質チェックの実施** - -- Lint/Format で新規エラーが導入されていないことを確認 -- 既存 warning との区別で、アップグレードの影響範囲を明確化