Merge pull request #30 from flycran/feat/calendar-list-option

feat: 新增内部调试参数 calendarList，集成测试移除模块 mock

Author: flycran

__tests__/fetchError.test.ts

@@ -0,0 +1,27 @@
+/**
+ * fetchContributions 失败时错误沿管道向上传播，且错误信息可读。
+ *
+ * 独立于 integration.test.ts：错误路径无法经 calendarList 注入，
+ * 是整个测试套件中唯一需要 mock 贡献模块的地方。
+ */
+import { describe, expect, it, mock } from 'bun:test'
+
+const mockFetchContributions = mock(async () => {
+  throw new Error(
+    'Failed to fetch contributions for "nonexistent": 404 Not Found'
+  )
+})
+mock.module('../src/utils/githubContributions.ts', () => ({
+  fetchContributions: mockFetchContributions,
+  INTENSITY_COLORS: ['#ebedf0', '#9be9a8', '#40c463', '#30a14e', '#216e39']
+}))
+
+const { gensvg } = await import('../src/utils/gensvg.js')
+
+describe('fetchContributions error propagation', () => {
+  it('propagates the API error with a readable message', async () => {
+    await expect(
+      gensvg({ username: 'nonexistent', text: 'Test' })
+    ).rejects.toThrow('Failed to fetch contributions')
+  })
+})

__tests__/integration.test.ts

@@ -1,11 +1,33 @@
 /**
- * 集成测试：来自gensvg的完整管道→ 物理学→ 字体加载→ SVG输出。
+ * 集成测试：gensvg 的完整管道 → 物理模拟 → 字体加载 → SVG 输出。
+ *
+ * 贡献数据一律经 calendarList 注入，不 mock 贡献模块；
+ * 全局 fetch 替换为守卫，实现一旦回退到网络请求测试即失败。
  */
-import { afterEach, beforeEach, describe, expect, it, mock } from 'bun:test'
+import { afterAll, beforeAll, describe, expect, it } from 'bun:test'
+import { gensvg } from '../src/utils/gensvg.js'
 
-function mockContributionsResponse() {
+const originalFetch = globalThis.fetch
+
+/** 任何网络访问都意味着实现回退到了 fetchContributions，直接失败并给出原因 */
+async function fetchGuard(): Promise<Response> {
+  throw new Error(
+    'unexpected network access: contributions must come from calendarList in tests'
+  )
+}
+
+beforeAll(() => {
+  globalThis.fetch = fetchGuard as unknown as typeof globalThis.fetch
+})
+
+afterAll(() => {
+  globalThis.fetch = originalFetch
+})
+
+/** 一周的贡献数据（一列），count 为 0 的天不生成方块 */
+function makeCalendarList() {
   return {
-    total: 7,
+    total: 46,
     contributions: [
       [
         { date: '2026-07-19', intensity: 1, count: 1 },
@@ -20,31 +42,14 @@ function mockContributionsResponse() {
   }
 }
 
-const mockFetchContributions = mock(async () => mockContributionsResponse())
-mock.module('../src/utils/githubContributions.ts', () => ({
-  fetchContributions: mockFetchContributions,
-  INTENSITY_COLORS: ['#ebedf0', '#9be9a8', '#40c463', '#30a14e', '#216e39']
-}))
-
-const { gensvg } = await import('../src/utils/gensvg.js')
-
 describe('full pipeline integration', () => {
-  beforeEach(() => {
-    mockFetchContributions.mockImplementation(async () =>
-      mockContributionsResponse()
-    )
-  })
-
-  afterEach(() => {
-    mockFetchContributions.mockReset()
-  })
-
   it('generates a valid SVG with contributions and text paths', async () => {
     const svg = await gensvg({
       username: 'testuser',
       text: 'Hi',
       fontSize: 40,
-      shape: 'circle'
+      shape: 'circle',
+      calendarList: makeCalendarList()
     })
 
     expect(typeof svg).toBe('string')
@@ -65,7 +70,8 @@ describe('full pipeline integration', () => {
       username: 'testuser',
       text: 'Hi',
       fontSize: 40,
-      shape: 'square'
+      shape: 'square',
+      calendarList: makeCalendarList()
     })
 
     expect(svg).toContain('<rect')
@@ -77,7 +83,8 @@ describe('full pipeline integration', () => {
       username: 'testuser',
       text: 'Hi',
       fontSize: 40,
-      shape: 'square'
+      shape: 'square',
+      calendarList: makeCalendarList()
     })
     // 方形会翻滚：平移之外再叠加绕方块中心的自转
     expect(square).toContain('type="rotate"')
@@ -86,7 +93,8 @@ describe('full pipeline integration', () => {
     const circle = await gensvg({
       username: 'testuser',
       text: 'Hi',
-      fontSize: 40
+      fontSize: 40,
+      calendarList: makeCalendarList()
     })
     expect(circle).not.toContain('type="rotate"')
   })
@@ -95,42 +103,29 @@ describe('full pipeline integration', () => {
     const svg = await gensvg({
       username: 'testuser',
       text: '',
-      fontSize: 40
+      fontSize: 40,
+      calendarList: makeCalendarList()
     })
 
     expect(svg).toContain('<svg')
     expect(svg).toContain('</svg')
   })
 
-  it('throws on invalid username (API error)', async () => {
-    mockFetchContributions.mockImplementation(async () => {
-      throw new Error(
-        'Failed to fetch contributions for "nonexistent": 404 Not Found'
-      )
-    })
-
-    await expect(
-      gensvg({ username: 'nonexistent', text: 'Test' })
-    ).rejects.toThrow('Failed to fetch contributions')
-  })
-
   it('produces deterministic SVG for same inputs', async () => {
     const svg1 = await gensvg({
       username: 'testuser',
       text: 'OK',
       fontSize: 30,
-      shape: 'circle'
+      shape: 'circle',
+      calendarList: makeCalendarList()
     })
 
-    mockFetchContributions.mockImplementation(async () =>
-      mockContributionsResponse()
-    )
-
     const svg2 = await gensvg({
       username: 'testuser',
       text: 'OK',
       fontSize: 30,
-      shape: 'circle'
+      shape: 'circle',
+      calendarList: makeCalendarList()
     })
 
     expect(svg1).toBe(svg2)
@@ -141,7 +136,8 @@ describe('full pipeline integration', () => {
       username: 'testuser',
       text: 'Hi',
       fontSize: 40,
-      backgroundColor: '#1a1a2e'
+      backgroundColor: '#1a1a2e',
+      calendarList: makeCalendarList()
     })
 
     expect(svg).toContain('fill="#1a1a2e"')
@@ -152,7 +148,8 @@ describe('full pipeline integration', () => {
       username: 'testuser',
       text: 'Hi',
       fontSize: 40,
-      textColor: '#ff0000'
+      textColor: '#ff0000',
+      calendarList: makeCalendarList()
     })
 
     expect(svg).toContain('fill="#ff0000"')
@@ -162,7 +159,8 @@ describe('full pipeline integration', () => {
     const svg = await gensvg({
       username: 'testuser',
       text: 'Hi',
-      fontSize: 40
+      fontSize: 40,
+      calendarList: makeCalendarList()
     })
 
     // 默认开启压缩，轨迹携带 span 并输出 keyTimes
@@ -174,7 +172,8 @@ describe('full pipeline integration', () => {
       username: 'testuser',
       text: 'Hi',
       fontSize: 40,
-      compressionTolerance: 0
+      compressionTolerance: 0,
+      calendarList: makeCalendarList()
     })
 
     // 容差 0 为无损压缩：匀速直线/静止段被并段，keyTimes 还原真实节奏
@@ -185,13 +184,15 @@ describe('full pipeline integration', () => {
     const plain = await gensvg({
       username: 'testuser',
       text: 'Hi',
-      fontSize: 40
+      fontSize: 40,
+      calendarList: makeCalendarList()
     })
     const compressed = await gensvg({
       username: 'testuser',
       text: 'Hi',
       fontSize: 40,
-      compressionTolerance: 1.5
+      compressionTolerance: 1.5,
+      calendarList: makeCalendarList()
     })
 
     // keyTimes 首帧 0、末帧 1
@@ -205,7 +206,8 @@ describe('full pipeline integration', () => {
       text: 'Hi',
       fontSize: 40,
       compressionTolerance: 1.5,
-      disableCompression: true
+      disableCompression: true,
+      calendarList: makeCalendarList()
     })
 
     expect(svg).not.toContain('keyTimes')
@@ -215,7 +217,8 @@ describe('full pipeline integration', () => {
     const dflt = await gensvg({
       username: 'testuser',
       text: 'Hi',
-      fontSize: 40
+      fontSize: 40,
+      calendarList: makeCalendarList()
     })
     // viewBox 使用物理坐标（SCALE=1），显示尺寸再乘 scale 选项放大
     expect(dflt).toContain('width="900"')
@@ -229,7 +232,8 @@ describe('full pipeline integration', () => {
       width: 400,
       height: 200,
       size: 6,
-      interval: 2
+      interval: 2,
+      calendarList: makeCalendarList()
     })
 
     expect(custom).toContain('width="1200"')
@@ -242,14 +246,16 @@ describe('full pipeline integration', () => {
     const omitted = await gensvg({
       username: 'testuser',
       text: 'Hi',
-      fontSize: 40
+      fontSize: 40,
+      calendarList: makeCalendarList()
     })
     const explicitUndefined = await gensvg({
       username: 'testuser',
       text: 'Hi',
       fontSize: 40,
       compressionTolerance: undefined,
-      maxSimulationTime: undefined
+      maxSimulationTime: undefined,
+      calendarList: makeCalendarList()
     })
 
     // 键携带 undefined 与键不存在等效
@@ -261,7 +267,8 @@ describe('full pipeline integration', () => {
       username: 'testuser',
       text: 'Hi',
       fontSize: 40,
-      maxSimulationTime: 0.2
+      maxSimulationTime: 0.2,
+      calendarList: makeCalendarList()
     })
 
     // dur = 播放时长 = 模拟时长 / speed：0.2s × 3 倍速 = 0.6s 模拟时长 ≈ 18 步，
@@ -279,7 +286,8 @@ describe('full pipeline integration', () => {
       username: 'testuser',
       text: 'Hi',
       fontSize: 40,
-      font
+      font,
+      calendarList: makeCalendarList()
     })
 
     expect(svg).toContain('<path d="')
@@ -292,30 +300,22 @@ describe('full pipeline integration', () => {
         username: 'testuser',
         text: 'Hi',
         fontSize: 40,
-        font: '/nonexistent/font.ttf'
+        font: '/nonexistent/font.ttf',
+        calendarList: makeCalendarList()
       })
     ).rejects.toThrow('Failed to load font "/nonexistent/font.ttf"')
   })
 })
 
 describe('css animation engine', () => {
-  beforeEach(() => {
-    mockFetchContributions.mockImplementation(async () =>
-      mockContributionsResponse()
-    )
-  })
-
-  afterEach(() => {
-    mockFetchContributions.mockReset()
-  })
-
   // 只冒烟引擎切换本身；动画的具体声明失效会直接表现为不动/走样，浏览器里肉眼可见
   it('renders with a self-contained style block instead of animateTransform', async () => {
     const svg = await gensvg({
       username: 'testuser',
       text: 'Hi',
       fontSize: 40,
-      css: true
+      css: true,
+      calendarList: makeCalendarList()
     })
 
     expect(svg).toContain('<style>')
@@ -327,7 +327,8 @@ describe('css animation engine', () => {
       username: 'testuser',
       text: 'Hi',
       fontSize: 40,
-      css: true
+      css: true,
+      calendarList: makeCalendarList()
     })
 
     // 方块只携带「颜色 + 动画名」class，fill、几何与动画绑定全由公共规则提供
@@ -353,7 +354,8 @@ describe('css animation engine', () => {
       text: 'Hi',
       fontSize: 40,
       css: true,
-      shape: 'square'
+      shape: 'square',
+      calendarList: makeCalendarList()
     })
 
     expect(rectSvg).toContain('<rect class="f0 g0"/>')
@@ -366,7 +368,8 @@ describe('css animation engine', () => {
       text: 'Hi',
       fontSize: 40,
       css: true,
-      animation: 'none'
+      animation: 'none',
+      calendarList: makeCalendarList()
     })
 
     expect(svg).toContain('animation:none')
@@ -379,7 +382,8 @@ describe('css animation engine', () => {
         text: 'Hi',
         fontSize: 40,
         css: true,
-        animation: '2s;color:red'
+        animation: '2s;color:red',
+        calendarList: makeCalendarList()
       })
     ).rejects.toThrow('Invalid animation')
   })