# jsdom v26.1.0 → v27.3.0 アップデート計画

**作成日**: 2025-12-17

**対象バージョン**: v26.1.0 → v27.3.0（メジャーバージョンアップ）

**ステータス**: ✅ 完了（2025-12-17 実施）

**優先度**: 低（プロジェクトへの破壊的影響なし）

## 目次

1. [破壊的変更と影響](#破壊的変更と影響)
2. [便利な新機能・改善](#便利な新機能改善)
3. [検証チェックリスト](#検証チェックリスト)
4. [リファレンス](#リファレンス)

---

## 破壊的変更と影響

### 🟡 1. 仮想コンソール API の変更

| 項目       | v26.1.0           | v27.0.0+      |
| ---------- | ----------------- | ------------- |
| メソッド名 | `sendTo()`        | `forwardTo()` |
| オプション | `omitJSDOMErrors` | `jsdomErrors` |

**影響度**: ✅ 無（プロジェクトで使用なし）

**詳細**:

- プロジェクトのテストコードで virtualConsole の使用がない
- jsdom を直接操作するコードが存在しない

---

### 🟡 2. イベント API の変更

| 変更内容          | 詳細                                               |
| ----------------- | -------------------------------------------------- |
| `element.click()` | `MouseEvent` → `PointerEvent` を発火するように変更 |

**影響度**: ✅ 無（プロジェクトで直接的な使用なし）

**詳細**:

- ユニットテストで click イベント操作なし
- E2E テスト（Playwright）は実ブラウザを使用するため jsdom 非依存

---

### 🟡 3. CSS セレクタエンジンの切り替え

| 項目             | v26.1.0  | v27.0.0+                   |
| ---------------- | -------- | -------------------------- |
| セレクタエンジン | `nwsapi` | `@asamuzakjp/dom-selector` |

**影響度**: ✅ 改善（20+ バグ修正）

**詳細**:

- より高速で正確なセレクタマッチング
- CSS セレクタ関連の 20 個以上のバグが修正
- プロジェクトでは querySelector の複雑な使用がないため大きな影響なし

---

### 🟡 4. ユーザーエージェント スタイルシートの変更

| 項目             | v26.1.0      | v27.0.0+          |
| ---------------- | ------------ | ----------------- |
| スタイルシート源 | Chromium由来 | HTML Standard由来 |

**影響度**: ✅ 無（プロジェクトで使用なし）

**詳細**:

- `getComputedStyle()` を使用するテストがない
- プロジェクトではスタイル関連のテストを実施していない

---

### 🟡 5. Input 要素の pattern 属性の正規表現フラグ変更

| 項目           | v26.1.0 | v27.0.0+ |
| -------------- | ------- | -------- |
| 正規表現フラグ | `u`     | `v`      |

**影響度**: ✅ 無（プロジェクトで使用なし）

**詳細**:

- プロジェクトで `<input pattern="">` 属性を使用していない

---

### 🟡 6. Node.js 最小バージョン要件

| 項目         | v26.1.0  | v27.0.0+ |
| ------------ | -------- | -------- |
| 最小 Node.js | v18.0.0+ | v20.0.0+ |

**影響度**: ✅ 無（プロジェクトで満たしている）

**詳細**:

- 現在の環境は Node.js 22 で要件を満たす
- `package.json` で既に `engines.node` が適切に設定されている

---

## 便利な新機能・改善

### ✨ 1. 新イベントコンストラクタの追加

```typescript
// 以下が新規実装
new BeforeUnloadEvent();
new BlobEvent();
new DeviceMotionEvent();
new DeviceOrientationEvent();
new PointerEvent();
new PromiseRejectionEvent();
new TransitionEvent();
```

**用途**: より広範なイベントハンドリングが可能に

---

### ✨ 2. MouseEvent の改善

```typescript
// 新規プロパティ追加
mouseEvent.movementX;
mouseEvent.movementY;
```

**用途**: ポインタロック機能のサポート向上

---

### ✨ 3. CustomElements API の強化

```typescript
// 新規メソッド追加
window.customElements.getName(constructor);
```

**用途**: カスタム要素の名前取得が可能に

---

### ✨ 4. CSS セレクタとパーサの大幅改善

**改善点**:

- セレクタエンジン刷新による 20+ バグ修正
- ネストセレクタのサポート向上
- CSS パーサの精度向上
- CSSOM オブジェクト API の充実

**恩恵**:

- テストの正確性向上
- CSS マッチング結果の信頼性向上

---

### ✨ 5. Spec 準拠性の向上

**改善項目**:

- Window オブジェクトの spec 準拠
- `document.createEvent()` の正確性向上
- ElementInternals のアクセシビリティ機能修正

---

## 検証チェックリスト

| 項目                     | コマンド                    | 期待結果                   |
| ------------------------ | --------------------------- | -------------------------- |
| ユニットテスト実行       | `pnpm test:unit`            | すべてのテストが PASS      |
| テスト網羅率確認         | `pnpm test:unit --coverage` | カバレッジが現状以上を維持 |
| ビルド確認               | `pnpm build`                | エラーなくビルド完了       |
| E2E テスト（オプション） | `pnpm test:integration`     | すべてのテストが PASS      |

---

## 実装チェックリスト

- [x] `pnpm install` で依存関係を更新
- [x] `pnpm test:unit` で全テスト実行
- [x] テスト結果を確認
- [x] 破壊的変更がないことを確認

---

## 結論

**推奨**: ✅ **すぐにアップグレード可能**

**理由**:

1. プロジェクトで破壊的変更に該当する機能を使用していない
2. セレクタエンジンの改善により、テストのロバストネスが向上
3. Node.js 要件を満たしている
4. 既存テストスイートで動作確認可能

---

## 検証結果（2025-12-17 実施）

### 実施内容

- `pnpm install` で jsdom 26.1.0 → 27.3.0、@types/jsdom 21.1.7 → 27.0.0 に更新
- `pnpm test:unit` を実行

### 結果

✅ **全テスト合格**

- テストファイル: 28 個
- テスト件数: 1745 合格（1 スキップ）
- 実行時間: 16.84 秒

### 教訓

1. **メジャーバージョンアップでも安全**: 破壊的変更が実際に使用していない機能だったため、アップグレード影響なし
2. **計画段階での影響分析が有効**: 事前に破壊的変更をリスト化し、プロジェクト内の使用箇所を調査することで、スムーズなアップグレードが可能
3. **テストスイート信頼性**: 包括的なテスト（1700+ テスト）により、回帰バグの検出が容易
4. **CSS セレクタエンジン改善**: 新しいエンジンでテストがより正確になる可能性あり

---

## リファレンス

- [jsdom Changelog](https://github.com/jsdom/jsdom/blob/main/Changelog.md)
- [jsdom v27.0.0 Release Notes](https://github.com/jsdom/jsdom/releases/tag/27.0.0)
- [jsdom v27.3.0 Release Notes](https://github.com/jsdom/jsdom/releases/tag/27.3.0)
- [PR #2927](https://github.com/AtCoder-NoviSteps/AtCoderNoviSteps/pull/2927)
