From 3c759f14c2dbe12782b934faf7221a3a39d1b44b Mon Sep 17 00:00:00 2001 From: Harvey Zhao Date: Thu, 10 Sep 2026 18:44:08 +0800 Subject: [PATCH] test(refactor): [BASE-HARNESS-01] add isolated published API fixture --- ...6-09-10-BASE-HARNESS-01-browser-fixture.md | 13 +++ refactor/fixtures/README.md | 14 ++++ refactor/fixtures/api.html | 13 +++ refactor/fixtures/api.js | 74 +++++++++++++++++ refactor/plan.md | 9 +- refactor/progress.md | 8 +- refactor/scripts/browser-server.mjs | 83 +++++++++++++++++++ refactor/scripts/browser-server.test.mjs | 50 +++++++++++ refactor/tasks.json | 26 +++++- 9 files changed, 283 insertions(+), 7 deletions(-) create mode 100644 refactor/changes/2026-09-10-BASE-HARNESS-01-browser-fixture.md create mode 100644 refactor/fixtures/README.md create mode 100644 refactor/fixtures/api.html create mode 100644 refactor/fixtures/api.js create mode 100644 refactor/scripts/browser-server.mjs create mode 100644 refactor/scripts/browser-server.test.mjs diff --git a/refactor/changes/2026-09-10-BASE-HARNESS-01-browser-fixture.md b/refactor/changes/2026-09-10-BASE-HARNESS-01-browser-fixture.md new file mode 100644 index 000000000..82b180a18 --- /dev/null +++ b/refactor/changes/2026-09-10-BASE-HARNESS-01-browser-fixture.md @@ -0,0 +1,13 @@ +# BASE-HARNESS-01 最小发布包浏览器采集服务 + +- 日期:2026-09-10;分支:codex/compatible-modernization;起点:1d705b30。 +- 提交主题:`test(refactor): [BASE-HARNESS-01] add isolated published API fixture`。 +- BASE-02 的独立前置子任务;验收范围是夹具与 HTTP 服务,不包括实际浏览器 API 基线。 + +新增本地服务,从已校验 tarball 提供指定 JS 成员、从 docs 提供本地媒体;固定路由、限定报告写入和大小,缓存不进入仓库。api.html/api.js 准备公开描述符、配置、同步插件及事件调用采集;没有修改生产包或公开接口,没有新增依赖。 + +`node --test refactor/scripts/browser-server.test.mjs` 1 项通过:精确 tarball 字节、页面路由、媒体 Range、无效 Range、路径越界、未知产物和异源报告拒绝。`node --check refactor/fixtures/api.js` 与计划检查通过。Node 25.2.1,Windows。 + +Chrome 工具打开页、读取清单、重置后重试均失败,不能取得真实页面报告。用户明确答复先继续其他实施任务;BASE-02 标 blocked 并保留完整范围,后续恢复浏览器连接再捕获。HTTP 测试不能替代浏览器。服务和夹具维护说明见 fixtures/README.md。 + +本子任务完成后独立提交,下一项 ENG-01。可回退本提交,不影响生产功能;临时测试进程和缓存不代表测试完成。 diff --git a/refactor/fixtures/README.md b/refactor/fixtures/README.md new file mode 100644 index 000000000..21db58977 --- /dev/null +++ b/refactor/fixtures/README.md @@ -0,0 +1,14 @@ +# 发布基线浏览器夹具 + +`node refactor/scripts/browser-server.mjs` 在 127.0.0.1:8083 启动独立测试服务;ARTPLAYER_TEST_PORT 可更换端口。它不启动或修改用户的 Chrome,也不占用 docs 的 8082 开发服务。 + +- `/fixtures/api.html` 加载固定核心/chapter tarball 的真实 JS,准备捕获描述符、默认配置、utils/子系统/插件形状及基础调用。 +- `/releases//` 只读取 releases.json 明确登记的成员;启动时核对 archive 完整性,不使用未编译源码或 CDN latest。 +- `/assets/sample/` 读取本仓库样本,支持普通 bytes 范围请求。当前服务用于最小基线;不是完整 ENG-05 故障注入或 HTTP Range 兼容实现,不支持后缀/多段 Range。 +- 页面将 `public-api` 报告发送给同源 `/reports/api`,服务器保存 refactor/.cache/reports/api.json。最多 1 MiB;其他 Origin 和未知写入路径失败。临时报告不能自动覆盖冻结快照。 + +运行 `node --test refactor/scripts/browser-server.test.mjs` 验证真实 HTTP 服务返回原始 JS 字节、样本范围和路由隔离;`node --check refactor/fixtures/api.js` 只检查脚本语法。两者不能证明页面能在浏览器运行。 + +2026-09-10:Chrome 连接服务连续失败,用户要求先继续其他任务;api.html 尚未实际执行,没有 API 快照或浏览器通过记录。BASE-02 保持 blocked;恢复连接后打开完整 URL,确认页面 PASS、没有错误,再核对报告和来源、生成持久基线。 + +夹具与报告路径由基线任务维护;ENG-05 可复用并扩充受控等待、媒体错误和正式自动化。api.js 依据已核对源码设计断言,真实发布行为如有不同应调查并记录,不能修改断言来盲目通过。 diff --git a/refactor/fixtures/api.html b/refactor/fixtures/api.html new file mode 100644 index 000000000..1d492793b --- /dev/null +++ b/refactor/fixtures/api.html @@ -0,0 +1,13 @@ + + + +ArtPlayer published API baseline + +

Published API contract

+

Capturing...

+
+

+
+
+
+
diff --git a/refactor/fixtures/api.js b/refactor/fixtures/api.js
new file mode 100644
index 000000000..70e1cadc0
--- /dev/null
+++ b/refactor/fixtures/api.js
@@ -0,0 +1,74 @@
+/* global Artplayer, artplayerPluginChapter */
+(async () => {
+  const report = { kind: 'public-api', environment: { userAgent: navigator.userAgent }, checks: [], errors: [] }
+  const check = (name, result) => {
+    report.checks.push({ name, passed: Boolean(result) })
+    if (!result) throw new Error(name)
+  }
+  function descriptors(object) {
+    return Object.fromEntries(Object.getOwnPropertyNames(object).sort().map((name) => {
+      const d = Object.getOwnPropertyDescriptor(object, name)
+      return [name, {
+        enumerable: d.enumerable,
+        configurable: d.configurable,
+        ...(Object.hasOwn(d, 'value') ? { writable: d.writable, type: typeof d.value } : { get: typeof d.get, set: typeof d.set }),
+      }]
+    }))
+  }
+  function valueOf(input) {
+    if (typeof input === 'function') return { $function: true }
+    if (input === undefined) return { $undefined: true }
+    if (typeof input === 'number' && !Number.isFinite(input)) return { $number: String(input) }
+    if (Array.isArray(input)) return input.map(valueOf)
+    if (input && typeof input === 'object') return Object.fromEntries(Object.keys(input).sort().map(key => [key, valueOf(input[key])]))
+    return input
+  }
+  let art
+  try {
+    check('published core version', Artplayer.version === '5.4.0')
+    const defaults = valueOf(Artplayer.option)
+    art = new Artplayer({ container: '.player', url: '/assets/sample/video.mp4', muted: true, plugins: [artplayerPluginChapter()] })
+    check('constructor registers exact instance', Artplayer.instances.includes(art))
+    check('native media element exposed', art.video instanceof HTMLVideoElement)
+    check('chapter registered synchronously', art.plugins.artplayerPluginChapter?.name === 'artplayerPluginChapter')
+    const plugin = { name: 'baselineProbe', ping: () => 'pong' }
+    const added = art.plugins.add(() => plugin)
+    check('plugins.add returns synchronous registry', added === art.plugins)
+    check('plugin result methods callable', art.plugins.baselineProbe.ping() === 'pong')
+    let received = 0
+    const handler = amount => { received += amount }
+    check('on is chainable', art.on('baseline:event', handler) === art)
+    art.emit('baseline:event', 3)
+    art.off('baseline:event', handler)
+    art.emit('baseline:event', 7)
+    check('custom event on/emit/off', received === 3)
+    const integrations = {}
+    for (const name of ['template', 'events', 'controls', 'setting', 'contextmenu', 'layers', 'plugins', 'storage', 'subtitle', 'i18n']) {
+      integrations[name] = { own: descriptors(art[name]), prototype: descriptors(Object.getPrototypeOf(art[name])) }
+    }
+    report.snapshot = {
+      static: descriptors(Artplayer),
+      prototype: descriptors(Artplayer.prototype),
+      emitterPrototype: descriptors(Object.getPrototypeOf(Artplayer.prototype)),
+      defaults,
+      config: valueOf(Artplayer.config),
+      utilityDescriptors: descriptors(Artplayer.utils),
+      instance: descriptors(art),
+      chapterFactory: descriptors(artplayerPluginChapter),
+      chapterResult: descriptors(art.plugins.artplayerPluginChapter),
+      integrations,
+    }
+  }
+  catch (error) {
+    report.errors.push(error.message)
+  }
+  finally {
+    if (art) {
+      art.destroy(true)
+      report.checks.push({ name: 'instance cleanup', passed: !Artplayer.instances.includes(art) })
+    }
+  }
+  const response = await fetch('/reports/api', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(report) })
+  document.getElementById('status').textContent = response.ok && !report.errors.length && report.checks.every(c => c.passed) ? 'PASS: published API captured' : 'FAIL: inspect report'
+  document.getElementById('result').textContent = JSON.stringify({ environment: report.environment, checks: report.checks, errors: report.errors }, null, 2)
+})()
diff --git a/refactor/plan.md b/refactor/plan.md
index 8421af3d4..b65708708 100644
--- a/refactor/plan.md
+++ b/refactor/plan.md
@@ -2,9 +2,9 @@
 
 > 由 tasks.json 生成。请修改数据后运行 `node refactor/scripts/plan.mjs --write`,不要手改本表。
 
-基线:`40fcda6a37d0049d42e49c1e64e70d4fd9ba5f7f`。总任务 211 项,范围 22 个包及工作区/示例。
+基线:`40fcda6a37d0049d42e49c1e64e70d4fd9ba5f7f`。总任务 212 项,范围 22 个包及工作区/示例。
 
-状态:todo 198 / doing 0 / blocked 0 / done 13 / deferred 0。风险 L/M/H 表示兼容风险,不表示工期。
+状态:todo 197 / doing 0 / blocked 1 / done 14 / deferred 0。风险 L/M/H 表示兼容风险,不表示工期。
 
 前置依赖是启动条件;验收是完成条件。任务可以继续拆分,但不能复用或悄悄删除旧 ID。
 
@@ -59,7 +59,8 @@
 | ID | 范围 / 步骤 | 前置依赖 | 交付物 | 验收条件 | 风险 | 状态 |
 | --- | --- | --- | --- | --- | --- | --- |
 | BASE-01 | workspace
固定核心与试点的最小发布基线 | DOC-07 | 核心及 chapter 的 npm tarball/integrity、源码 SHA、已知支持窗口;其他包标待核对 | 核心/试点来源可重跑;不虚构全生态已验证,各包 01 步负责补齐自身历史发布基线 | H | done | -| BASE-02 | workspace
捕获公共 API 和属性描述符 | BASE-01 | 核心与试点的构造/默认值/静态和实例 API 快照,其余包由 01/02 步补齐;登记契约/版本/固定测试 ID/命令/报告与负责任务 | 真实发布包反射与旧用户调用可重跑,未验证项明确 | H | todo | +| BASE-HARNESS-01 | workspace
建立最小发布包浏览器采集夹具与服务 | BASE-01 | 固定 tarball 静态服务、本地媒体 Range、公开 API 采集页面及受控报告路径 | HTTP 精确内容/范围和路由隔离测试、夹具语法通过;浏览器采集仍由 BASE-02 负责 | M | done | +| BASE-02 | workspace
捕获公共 API 和属性描述符 | BASE-01, BASE-HARNESS-01 | 核心与试点的构造/默认值/静态和实例 API 快照,其余包由 01/02 步补齐;登记契约/版本/固定测试 ID/命令/报告与负责任务 | 真实发布包反射与旧用户调用可重跑,未验证项明确 | H | blocked | | BASE-03 | workspace
捕获事件、异步和生命周期 | BASE-02 | ready/restart/destroy、Promise、切源/插件事件 trace;登记契约/版本/固定测试 ID/命令/报告与负责任务 | 成功、失败、重入和多实例有断言,历史缺陷有标记;使用已发布包和最小可重跑探针启动,不等待后续 ENG 服务 | H | todo | | BASE-04 | workspace
捕获 DOM、CSS 和官方 demo | BASE-02 | 核心模板/类名/变量、键盘/焦点/可访问名称基线及全 demo 路径映射;docs-browser-testing.md 中 HTML/编辑器的脚本来源与存储状态;登记契约/版本/固定测试 ID/命令/报告与负责任务 | 核心/试点用户样式和输入用法已记录,其他 demo 运行状态与未知项明确;使用已发布包和最小可重跑探针启动,不等待后续 ENG 服务 | M | todo | | BASE-05 | workspace
捕获包入口、资源和类型消费 | BASE-01 | 全包 manifest/资源路径清单;核心/试点的 UMD/AMD/ESM/CJS/legacy/i18n 和类型消费者基线;登记契约/版本/固定测试 ID/命令/报告与负责任务;区分库/npm 与站点实际分发类别,SSR import/模板/非浏览器构造错误分别捕获 | 核心/试点隔离消费可运行,其他包由各自契约任务验证,thumbnail tool 差异已登记 | H | todo | @@ -413,3 +414,5 @@ - DOC-11: [记录](changes/2026-09-10-DOC-11-major-version-policy.md) - DOC-12: [记录](changes/2026-09-10-DOC-12-execution-readiness-review.md) - BASE-01: [记录](changes/2026-09-10-BASE-01-published-baseline.md) [记录](baselines/releases.json) +- BASE-HARNESS-01: [记录](changes/2026-09-10-BASE-HARNESS-01-browser-fixture.md) +- BASE-02: Chrome 工具连接连续失败,重置后仍不可用;用户要求先继续其他任务。恢复连接后执行 api.html 并核对报告,HTTP 服务通过不代表浏览器通过。 diff --git a/refactor/progress.md b/refactor/progress.md index 6a4fb129e..7e3542eee 100644 --- a/refactor/progress.md +++ b/refactor/progress.md @@ -1,6 +1,12 @@ # 进度与证据 -## 当前实施:BASE-01 已发布基线 +## 当前实施:浏览器夹具已保存,继续 ENG-01 + +BASE-01 已提交 `1d705b30`。BASE-HARNESS-01 完成发布包采集页面/本地 HTTP 服务及 1 项真实 HTTP 测试,详见 [交付记录](changes/2026-09-10-BASE-HARNESS-01-browser-fixture.md)。BASE-02 因 Chrome 连接失败保持 blocked;用户要求先继续其他实施任务,没有伪造浏览器基线。 + +完成 12 项规划、2 项实施基础任务;BASE-02 阻塞,其余 197 项待办。没有生产 TS 迁移。下一项 ENG-01 固定依赖和运行环境,浏览器恢复后继续 BASE-02。 + +## 2026-09-10:BASE-01 已发布基线 2026-09-10,goal 开始执行。固定核心 5.4.0/chapter 1.1.0 的真实 tarball、47 个成员哈希和支持范围未知项。核心工作区 5.4.1 未发布,两包 registry gitHead 版本过旧,均已如实记录。详见 [BASE-01 交付](changes/2026-09-10-BASE-01-published-baseline.md)。 diff --git a/refactor/scripts/browser-server.mjs b/refactor/scripts/browser-server.mjs new file mode 100644 index 000000000..9b4543f36 --- /dev/null +++ b/refactor/scripts/browser-server.mjs @@ -0,0 +1,83 @@ +import assert from 'node:assert/strict' +import fs from 'node:fs' +import http from 'node:http' +import path from 'node:path' +import { ensureArchive, readMember, refactorDir } from './releases.mjs' + +const root = path.resolve(refactorDir, '..') +const baseline = JSON.parse(fs.readFileSync(path.join(refactorDir, 'baselines/releases.json'), 'utf8')) +const archives = new Map() +for (const release of baseline.releases) archives.set(release.name, await ensureArchive(release)) +const mime = { '.html': 'text/html', '.js': 'text/javascript', '.mjs': 'text/javascript', '.json': 'application/json', '.mp4': 'video/mp4', '.webm': 'video/webm', '.vtt': 'text/vtt', '.png': 'image/png' } +let port = Number(process.env.ARTPLAYER_TEST_PORT || 8083) +assert(Number.isInteger(port) && port >= 0 && port < 65536, 'Invalid test port') + +function sendBytes(req, res, bytes, filename) { + res.setHeader('Content-Type', mime[path.extname(filename)] || 'application/octet-stream') + res.setHeader('Cache-Control', 'no-store') + res.setHeader('Accept-Ranges', 'bytes') + const range = req.headers.range + if (range) { + const match = /^bytes=(\d+)-(\d*)$/.exec(range) + const start = match ? Number(match[1]) : -1 + const end = match?.[2] ? Math.min(Number(match[2]), bytes.length - 1) : bytes.length - 1 + if (start < 0 || start >= bytes.length || end < start) { + res.writeHead(416, { 'Content-Range': `bytes */${bytes.length}` }) + res.end() + return + } + res.statusCode = 206 + res.setHeader('Content-Range', `bytes ${start}-${end}/${bytes.length}`) + bytes = bytes.subarray(start, end + 1) + } + res.setHeader('Content-Length', bytes.length) + res.end(req.method === 'HEAD' ? undefined : bytes) +} + +const server = http.createServer(async (req, res) => { + try { + const url = new URL(req.url, `http://127.0.0.1:${port}`) + if (req.method === 'POST' && url.pathname === '/reports/api') { + assert.equal(req.headers.origin, `http://127.0.0.1:${port}`, 'Unexpected report origin') + const chunks = [] + let size = 0 + for await (const chunk of req) { + size += chunk.length + assert(size <= 1024 * 1024, 'Report too large') + chunks.push(chunk) + } + const report = JSON.parse(Buffer.concat(chunks).toString('utf8')) + assert.equal(report.kind, 'public-api') + const output = path.join(refactorDir, '.cache/reports') + fs.mkdirSync(output, { recursive: true }) + fs.writeFileSync(path.join(output, 'api.json'), `${JSON.stringify(report, null, 2)}\n`) + res.writeHead(204).end() + return + } + assert(['GET', 'HEAD'].includes(req.method), 'Unsupported method') + if (url.pathname.startsWith('/releases/')) { + const [, , name, ...parts] = url.pathname.split('/') + const release = baseline.releases.find(item => item.name === name) + const member = `package/${parts.join('/')}` + assert(release && Object.hasOwn(release.files, member), 'Unknown release member') + sendBytes(req, res, readMember(archives.get(name), member), member) + return + } + const prefix = url.pathname.startsWith('/assets/sample/') ? '/assets/sample/' : '/fixtures/' + assert(url.pathname.startsWith(prefix), 'Unknown test route') + const dir = prefix === '/fixtures/' ? path.join(refactorDir, 'fixtures') : path.join(root, 'docs/assets/sample') + const filename = path.resolve(dir, decodeURIComponent(url.pathname.slice(prefix.length))) + const relative = path.relative(dir, filename) + assert(relative && !relative.startsWith('..') && !path.isAbsolute(relative), 'Invalid fixture path') + sendBytes(req, res, fs.readFileSync(filename), filename) + } + catch (error) { + if (!res.headersSent) res.writeHead(400, { 'Content-Type': 'text/plain' }) + res.end(error.message) + } +}) +server.listen(port, '127.0.0.1', () => { + port = server.address().port + console.log(`Baseline browser server: http://127.0.0.1:${port}/fixtures/api.html`) +}) +for (const signal of ['SIGINT', 'SIGTERM']) process.on(signal, () => server.close()) diff --git a/refactor/scripts/browser-server.test.mjs b/refactor/scripts/browser-server.test.mjs new file mode 100644 index 000000000..ad8c88da5 --- /dev/null +++ b/refactor/scripts/browser-server.test.mjs @@ -0,0 +1,50 @@ +import assert from 'node:assert/strict' +import { spawn } from 'node:child_process' +import { once } from 'node:events' +import fs from 'node:fs' +import path from 'node:path' +import { test } from 'node:test' +import { hash, refactorDir } from './releases.mjs' + +test('baseline host serves exact release bytes, media ranges and isolated routes', { timeout: 15000 }, async () => { + const child = spawn(process.execPath, [path.join(refactorDir, 'scripts/browser-server.mjs')], { + env: { ...process.env, ARTPLAYER_TEST_PORT: '0' }, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true, + }) + let timer + try { + const origin = await new Promise((resolve, reject) => { + let output = '' + timer = setTimeout(() => reject(new Error('Host did not start')), 10000) + child.once('error', reject) + child.once('exit', code => reject(new Error(`Host exited: ${code}`))) + child.stdout.on('data', (chunk) => { + output += chunk + const match = output.match(/http:\/\/127\.0\.0\.1:\d+/) + if (match) { clearTimeout(timer); resolve(match[0]) } + }) + }) + const baseline = JSON.parse(fs.readFileSync(path.join(refactorDir, 'baselines/releases.json'), 'utf8')) + const response = await fetch(`${origin}/releases/artplayer/dist/artplayer.js`) + assert.equal(response.status, 200) + assert.equal(hash(Buffer.from(await response.arrayBuffer())), baseline.releases[0].files['package/dist/artplayer.js']) + const html = await fetch(`${origin}/fixtures/api.html`) + assert.equal(html.status, 200) + assert((await html.text()).includes('/releases/artplayer-plugin-chapter/')) + const media = fs.readFileSync(path.resolve(refactorDir, '../docs/assets/sample/video.mp4')) + const range = await fetch(`${origin}/assets/sample/video.mp4`, { headers: { Range: 'bytes=0-31' } }) + assert.equal(range.status, 206) + assert.equal(range.headers.get('content-range'), `bytes 0-31/${media.length}`) + assert.deepEqual(Buffer.from(await range.arrayBuffer()), media.subarray(0, 32)) + const invalid = await fetch(`${origin}/assets/sample/video.mp4`, { headers: { Range: `bytes=${media.length}-` } }) + assert.equal(invalid.status, 416) + assert.equal((await fetch(`${origin}/fixtures/%2e%2e%2fbaselines/releases.json`)).status, 400) + assert.equal((await fetch(`${origin}/releases/artplayer/no-such-member.js`)).status, 400) + assert.equal((await fetch(`${origin}/reports/api`, { method: 'POST', headers: { Origin: 'https://example.com' }, body: '{}' })).status, 400) + } + finally { + clearTimeout(timer) + const exited = once(child, 'exit') + child.kill() + await exited + } +}) diff --git a/refactor/tasks.json b/refactor/tasks.json index 9cddd8fa0..ff711ad51 100644 --- a/refactor/tasks.json +++ b/refactor/tasks.json @@ -238,6 +238,24 @@ "baselines/releases.json" ] }, + { + "id": "BASE-HARNESS-01", + "phase": "1 基线", + "title": "建立最小发布包浏览器采集夹具与服务", + "scope": [ + "workspace" + ], + "dependsOn": [ + "BASE-01" + ], + "status": "done", + "risk": "M", + "deliverable": "固定 tarball 静态服务、本地媒体 Range、公开 API 采集页面及受控报告路径", + "acceptance": "HTTP 精确内容/范围和路由隔离测试、夹具语法通过;浏览器采集仍由 BASE-02 负责", + "evidence": [ + "changes/2026-09-10-BASE-HARNESS-01-browser-fixture.md" + ] + }, { "id": "BASE-02", "phase": "1 基线", @@ -246,13 +264,15 @@ "workspace" ], "dependsOn": [ - "BASE-01" + "BASE-01", + "BASE-HARNESS-01" ], - "status": "todo", + "status": "blocked", "risk": "H", "deliverable": "核心与试点的构造/默认值/静态和实例 API 快照,其余包由 01/02 步补齐;登记契约/版本/固定测试 ID/命令/报告与负责任务", "acceptance": "真实发布包反射与旧用户调用可重跑,未验证项明确", - "evidence": [] + "evidence": [], + "reason": "Chrome 工具连接连续失败,重置后仍不可用;用户要求先继续其他任务。恢复连接后执行 api.html 并核对报告,HTTP 服务通过不代表浏览器通过。" }, { "id": "BASE-03",