jest-fixme 插件概念說明

一個自訂的 Jest 插件，提供 fixme() API，讓測試可以正常執行，但即使發生錯誤也不會導致整個測試結果失敗，並獨立顯示統計。

安裝 (Installation)

# 使用 yarn / Using yarn
yarn add jest-plugin-fixme-suite

# 使用 pnpm / Using pnpm
pnpm add jest-plugin-fixme-suite

# 使用 npm / Using npm
npm install jest-plugin-fixme-suite

核心概念

設計概念

1. fixme 測試函數

• 強化原生 test()
• 捕捉到錯誤後 不重新拋出，讓 Jest 認為該測試通過
• 記錄每個 fixme 的標題、執行結果（passed/failed）和錯誤資訊

2. 自訂 Reporter

• 建立一個 Jest Custom Reporter
• 統計並顯示通過與失敗的 fixme 數量
• 清楚標註「這些失敗不會影響整體測試結果」

3. 整合方式

• 透過 setupFilesAfterEnv 載入 fixme 函數並掛載到 global.fixme
• 在 jest.config.js 的 reporters 中加入自訂 reporter
• 支援 fixme.skip、fixme.only、fixme.todo

與 test()、it() 的差異

| 特性 | test() / it() | fixme() | |------|---------------|---------| | 執行測試 | ✓ | ✓ | | 失敗導致 suite 失敗 | ✓ | ✗ | | 顯示統計資訊 | ✗ | ✓ | | 支援 skip/only/todo | ✓ | ✓ |

適用場景

• 標記「已知問題、正在處理」的測試
• 不影響正常測試的失敗判定
• 方便團隊追蹤待修復項目
• 測試仍然會完整運行，可用來驗證其他相關功能是否受影響

注意事項

• fixme 測試依然會執行所有 hook（beforeAll、afterEach 等）
• 統計資訊透過 global 變數在 reporter 中取得
• fixme 失敗不會讓 CI 變紅，適合過渡時期使用

輸出範例 (Output Example)

執行測試後，Reporter 會顯示類似以下的輸出：

=============================
🔧 FIXME SUMMARY
=============================
✅ 修復中的功能 A
❌ 修復中的功能 B
   → Expected values to be strictly equal:
=============================
📊 3 fixme, 1 passed, 2 failed
(這些失敗不會影響整體測試結果 / CI 狀態)
=============================

常見問題 (FAQ)

Q: fixme 測試真的會執行嗎？

是的，fixme 測試會真正執行，包含所有 expect、async、beforeEach 等，與一般 test() 無異。

Q: 為什麼不直接使用 test.skip()？

test.skip() 完全不會執行測試，而 fixme() 會執行但不影響整體結果。

Q: 如何查看 fixme 統計？

Reporter 會在測試結束後自動顯示統計資訊，格式為「N fixme, X passed, Y failed」。

Q: fixme 失敗會讓 CI 變紅嗎？

不會。fixme 的設計就是要讓失敗不影響整體測試結果，CI 狀態會維持正常。

此設計概念可直接實作，達到與 jest.todo、jest.skip 類似的便利性，但行為更接近「執行但不計失敗」。

API 說明 (API Reference)

fixme(title, fn, timeout)

與 test() 使用方式相同，但失敗不會影響整體測試結果。

| 參數 | 類型 | 說明 | |------|------|------| | title | string | 測試標題 | | fn | function | 測試函式（同步或 async） | | timeout | number | 逾時時間（毫秒，可選） |

fixme.skip(title, fn, timeout)

跳過 fixme 測試。

fixme.only(title, fn, timeout)

只執行該 fixme 測試。

fixme.todo(title)

建立一個待辦的 fixme 測試。

鏈式語法 (Chainable Syntax)

it.fixme('標題', () => { /* ... */ })
test.fixme('標題', () => { /* ... */ })
it.fixme.skip('標題', () => { /* ... */ })
test.fixme.only('標題', () => { /* ... */ })

設定選項 (Configuration Options)

環境變數

# 禁用 FIXME SUMMARY 顯示（預設：顯示）
JEST_FIXME_DISABLE_SUMMARY=true

# 禁用 fixme 詳細結果顯示（預設：顯示）
JEST_FIXME_DISABLE_DETAILS=true

setupFilesAfterEnv

// 方式一：使用套件內建的 setup
// Method 1: Use built-in setup from package
setupFilesAfterEnv: ['jest-plugin-fixme-suite/jest-fixme-setup']

// 方式二：建立自訂 setup 檔案
// Method 2: Create custom setup file
setupFilesAfterEnv: ['<rootDir>/my-fixme-setup.js']

自訂 Reporter 設定

// 基本設定 / Basic configuration
reporters: [
  'default',
  'jest-plugin-fixme-suite/jest-fixme-reporter',
]

// 與其他 Reporter 混合使用 / Mix with other reporters
reporters: [
  ['jest-junit', { outputName: 'jest-results.xml' }],
  'default',
  'jest-plugin-fixme-suite/jest-fixme-reporter',
]

快速開始 (Quick Start)

1. 建立 setup 檔案

建立 jest-fixme-setup.js 或 jest-fixme-setup.ts 檔案：

// jest-fixme-setup.js
const { setupFixme } = require('jest-plugin-fixme-suite/jest-fixme-setup');

setupFixme();

2. 修改 Jest 設定

在 jest.config.js 中設定：

module.exports = {
  // 必須設定 setupFilesAfterEnv 以在測試環境初始化後載入 fixme
  // Must set setupFilesAfterEnv to load fixme after test environment is initialized
  setupFilesAfterEnv: ['<rootDir>/jest-fixme-setup.js'],
  
  // 添加自訂 Reporter 來顯示 fixme 統計
  // Add custom Reporter to display fixme statistics
  reporters: [
    'default',
    'jest-plugin-fixme-suite/jest-fixme-reporter',
  ],
};

3. 在測試中使用 fixme

// test/example.test.js

// 基本用法 / Basic usage
fixme('這個功能還在修復中，但我想持續執行測試', () => {
  expect(currentImplementation()).toEqual(expectedResult);
});

// 支援 async 測試 / Support async tests
fixme('async 測試範例', async () => {
  const result = await someAsyncFunction();
  expect(result).toBe(true);
});

// 使用 skip / Using skip
fixme.skip('跳過的 fixme 測試', () => {
  expect(true).toBe(false);
});

// 使用 only / Using only
fixme.only('只執行這個 fixme', () => {
  expect(true).toBe(true);
});

// 也支援鏈式語法 / Also supports chainable syntax
it.fixme('透過 it.fixme 使用', () => {
  expect(true).toBe(false);
});

test.fixme('透過 test.fixme 使用', () => {
  expect(true).toBe(false);
});

類型定義 (Type Definitions)

套件提供完整的 TypeScript 類型定義：

import { 
  IFixmeResult, 
  IFixmeFunction, 
  createFixmeFunction,
  initFixme,
  fixmeResults 
} from 'jest-plugin-fixme-suite';