@pls-compile-owo/fisheye 0.4.2 → 0.7.2

package/test/progress.test.mjs

@@ -0,0 +1,139 @@
+// progress 模块单测：进度计数 / 单行覆盖 / 静默 / 时长格式化 / 阶段计时
+// 用注入的假 stream 收集输出，不碰真实 stderr。
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { createProgress, stageTimer, humanDuration } from '../lib/progress.mjs'
+
+function fakeStream({ isTTY = false } = {}) {
+  return {
+    isTTY,
+    chunks: [],
+    write(s) { this.chunks.push(s) },
+  }
+}
+
+const text = (out) => out.chunks.join('')
+
+test('createProgress：tick 累计、set 跳转、done 收尾（非 TTY 每行换行）', () => {
+  const out = fakeStream()
+  const p = createProgress('抽帧', 12, { stream: out })
+  p.tick()
+  p.tick()
+  p.tick()
+  p.set(9)
+  p.tick(2)
+  const sec = p.done()
+
+  assert.equal(typeof sec, 'number')
+  assert.deepEqual(out.chunks, [
+    '[抽帧] 1/12 (8%)\n',
+    '[抽帧] 2/12 (16%)\n',
+    '[抽帧] 3/12 (25%)\n',
+    '[抽帧] 9/12 (75%)\n',
+    '[抽帧] 11/12 (91%)\n',
+    '[抽帧] 12/12 (100%)\n',
+  ])
+  assert.ok(!text(out).includes('\r'), '非 TTY 不该用 \\r 覆盖')
+})
+
+test('createProgress：TTY 用 \\r 单行覆盖，done 时补换行', () => {
+  const out = fakeStream({ isTTY: true })
+  const p = createProgress('下载', 4, { stream: out })
+  p.tick()
+  p.tick(2)
+  assert.ok(out.chunks.every((c) => c.startsWith('\r')))
+  assert.ok(!text(out).includes('\n'), 'done 之前不能换行')
+
+  p.done()
+  assert.equal(text(out), '\r[下载] 1/4 (25%)\r[下载] 3/4 (75%)\r[下载] 4/4 (100%)\n')
+})
+
+test('createProgress：tick 超过总数时停在 100%', () => {
+  const out = fakeStream()
+  const p = createProgress('x', 3, { stream: out })
+  p.tick(10)
+  assert.equal(out.chunks.at(-1), '[x] 3/3 (100%)\n')
+})
+
+test('createProgress：total 未知（0）时只显示计数', () => {
+  const out = fakeStream()
+  const p = createProgress('帧', 0, { stream: out })
+  p.tick()
+  p.tick(2)
+  assert.deepEqual(out.chunks, ['[帧] 1\n', '[帧] 3\n'])
+})
+
+test('createProgress：enabled:false 时完全静默，elapsed 仍可用', () => {
+  const out = fakeStream()
+  const p = createProgress('x', 5, { stream: out, enabled: false })
+  p.tick()
+  p.set(3)
+  p.done()
+  p.fail('boom')
+  assert.equal(text(out), '')
+  assert.equal(typeof p.elapsed(), 'number')
+  assert.ok(p.elapsed() >= 0)
+})
+
+test('createProgress：fail 输出原因，之后不再输出', () => {
+  const out = fakeStream()
+  const p = createProgress('下载', 4, { stream: out })
+  p.tick()
+  p.fail('网络断了')
+  p.tick()
+  p.done()
+  assert.equal(out.chunks.length, 2)
+  assert.equal(out.chunks[0], '[下载] 1/4 (25%)\n')
+  assert.match(out.chunks[1], /^\[下载\] 失败：网络断了\n$/)
+})
+
+test('createProgress：elapsed 返回非负秒数', () => {
+  const p = createProgress('x', 1, { stream: fakeStream() })
+  const sec = p.elapsed()
+  assert.equal(typeof sec, 'number')
+  assert.ok(sec >= 0 && sec < 5)
+})
+
+test('createProgress / stageTimer：stream 不能写时不抛', () => {
+  const p = createProgress('x', 1, { stream: {} })
+  p.tick()
+  p.done()
+  p.fail('no-write')
+  const timer = stageTimer('y', { stream: {} })
+  timer.stop()
+})
+
+test('humanDuration：ms / s / m / h 格式化', () => {
+  assert.equal(humanDuration(0), '0ms')
+  assert.equal(humanDuration(300), '300ms')
+  assert.equal(humanDuration(1500), '1.5s')
+  assert.equal(humanDuration(59000), '59.0s')
+  assert.equal(humanDuration(60000), '1m0s')
+  assert.equal(humanDuration(123000), '2m3s')
+  assert.equal(humanDuration(3723000), '1h2m3s')
+  // 异常输入不该产出 NaN
+  assert.equal(humanDuration(-5), '0ms')
+  assert.equal(humanDuration(NaN), '0ms')
+  assert.equal(humanDuration(undefined), '0ms')
+})
+
+test('stageTimer：stop 输出用时、返回秒数、重复 stop 只输出一次', () => {
+  const out = fakeStream()
+  const timer = stageTimer('下载', { stream: out })
+  const sec = timer.stop()
+  assert.equal(typeof sec, 'number')
+  assert.ok(sec >= 0)
+  assert.equal(out.chunks.length, 1)
+  assert.match(out.chunks[0], /^\[下载\] 用时 (\d+ms|\d+\.\d+s|\d+m\d+s|\d+h\d+m\d+s)\n$/)
+
+  timer.stop()
+  assert.equal(out.chunks.length, 1, '重复 stop 不应重复输出')
+})
+
+test('stageTimer：enabled:false 时静默', () => {
+  const out = fakeStream()
+  const timer = stageTimer('精读', { stream: out, enabled: false })
+  const sec = timer.stop()
+  assert.equal(text(out), '')
+  assert.equal(typeof sec, 'number')
+})

package/test/resume.test.mjs

@@ -0,0 +1,232 @@
+// resume 模块单测：manifest 读写 / 可复用判定 / 阶段记录 / 人类可读摘要
+// 数据全在 os.tmpdir() 的临时目录里造，跑完清理，不碰项目自己的 out/。
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import {
+  loadManifestState,
+  saveManifest,
+  manifestPath,
+  canResume,
+  recordStage,
+  markDone,
+  resumeSummary,
+} from '../lib/resume.mjs'
+
+function tmpDir(t) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'fisheye-resume-'))
+  t.after(() => fs.rmSync(dir, { recursive: true, force: true }))
+  return dir
+}
+
+/** 造一张「存在且非空」的拼图文件（内容无所谓，续跑只看文件在不在） */
+function writeSheet(dir, name) {
+  const file = path.join(dir, name)
+  fs.writeFileSync(file, 'fake-jpeg')
+  return file
+}
+
+const PLAN = { budget: 20000, density: 6, from: 0, to: 600 }
+
+/** 一份完整的 manifest：下载已 done，两张拼图，计划参数固定 */
+function makeState(t, { bvid = 'BV1resume001' } = {}) {
+  const dir = tmpDir(t)
+  const a = writeSheet(dir, 'c00_0000-0300_3x3.jpg')
+  const b = writeSheet(dir, 'c01_0300-0600_3x3.jpg')
+  const state = {
+    bvid,
+    title: '断点续跑测试片',
+    duration: 600,
+    grid: '3x3',
+    plan: { ...PLAN },
+    range: { from: 0, to: 600 },
+    // 第一条用 sheet（stageGrid 现在的写法），第二条用 file（新写法）——两种都要认
+    chunks: [
+      { chunk: 1, from: 0, to: 300, range: '00:00-05:00', grid: '3x3', sheet: a },
+      { chunk: 2, from: 300, to: 600, range: '05:00-10:00', grid: '3x3', file: b },
+    ],
+    stages: { download: { status: 'done' } },
+    createdAt: '2026-01-01T00:00:00.000Z',
+  }
+  saveManifest(dir, bvid, state)
+  return { dir, bvid, state, sheets: [a, b] }
+}
+
+test('loadManifestState：读回 manifest；不存在 / 坏 JSON → null；BOM 能读', (t) => {
+  const { dir, bvid, state } = makeState(t)
+  const got = loadManifestState(dir, bvid)
+  assert.equal(got.bvid, bvid)
+  assert.equal(got.title, state.title)
+  assert.deepEqual(got.chunks, state.chunks)
+  assert.equal(manifestPath(dir, bvid), path.join(dir, `${bvid}-manifest.json`))
+
+  assert.equal(loadManifestState(dir, 'BVnothere'), null)
+
+  fs.writeFileSync(manifestPath(dir, bvid), '{ 这不是 json', 'utf8')
+  assert.equal(loadManifestState(dir, bvid), null)
+
+  // PowerShell / 记事本会加 BOM
+  fs.writeFileSync(manifestPath(dir, bvid), '\uFEFF{"bvid":"x"}', 'utf8')
+  assert.equal(loadManifestState(dir, bvid).bvid, 'x')
+})
+
+test('saveManifest：校验参数，写出的内容能原样读回，且不留临时文件', (t) => {
+  const dir = tmpDir(t)
+  assert.throws(() => saveManifest(dir, '', {}), TypeError)
+  assert.throws(() => saveManifest(dir, 'BVx', null), TypeError)
+
+  const file = saveManifest(dir, 'BVx', { bvid: 'BVx', chunks: [] })
+  assert.equal(file, manifestPath(dir, 'BVx'))
+  assert.deepEqual(JSON.parse(fs.readFileSync(file, 'utf8')), { bvid: 'BVx', chunks: [] })
+  assert.deepEqual(fs.readdirSync(dir).filter((f) => f.endsWith('.tmp')), [])
+})
+
+test('canResume：文件都在、计划参数没变 → 可复用并给出张数', (t) => {
+  const { dir, bvid } = makeState(t)
+  const r = canResume(loadManifestState(dir, bvid), { plan: { ...PLAN } })
+  assert.equal(r.resumable, true)
+  assert.equal(r.doneGrids, 2)
+  assert.match(r.reason, /2\/2/)
+  assert.match(r.reason, /跳过抽帧/)
+})
+
+test('canResume：缺一张 / 空文件 → 仍可复用，只补缺的', (t) => {
+  const { dir, bvid, sheets } = makeState(t)
+  fs.unlinkSync(sheets[1])
+  let r = canResume(loadManifestState(dir, bvid), { plan: { ...PLAN } })
+  assert.equal(r.resumable, true)
+  assert.equal(r.doneGrids, 1)
+  assert.match(r.reason, /1\/2/)
+  assert.match(r.reason, /补抽 1 张/)
+
+  // 0 字节的图不能算「已抽好」
+  fs.writeFileSync(sheets[0], '')
+  r = canResume(loadManifestState(dir, bvid), { plan: { ...PLAN } })
+  assert.equal(r.resumable, false)
+  assert.equal(r.doneGrids, 0)
+})
+
+test('canResume：拼图全没了 → 抽帧要重来（不可复用）', (t) => {
+  const { dir, bvid, sheets } = makeState(t)
+  for (const f of sheets) fs.unlinkSync(f)
+  const r = canResume(loadManifestState(dir, bvid), { plan: { ...PLAN } })
+  assert.equal(r.resumable, false)
+  assert.equal(r.doneGrids, 0)
+  assert.match(r.reason, /全部缺失/)
+})
+
+test('canResume：budget / density 变了 → 抽帧不能跳过', (t) => {
+  const { dir, bvid } = makeState(t)
+  const byBudget = canResume(loadManifestState(dir, bvid), { plan: { ...PLAN, budget: 50000 } })
+  assert.equal(byBudget.resumable, false)
+  assert.match(byBudget.reason, /budget/)
+  assert.match(byBudget.reason, /20000/)
+
+  const byDensity = canResume(loadManifestState(dir, bvid), { plan: { ...PLAN, density: 3 } })
+  assert.equal(byDensity.resumable, false)
+  assert.match(byDensity.reason, /density/)
+})
+
+test('canResume：时间区间变了 → 时间轴对不上，不能复用', (t) => {
+  const { dir, bvid } = makeState(t)
+  const r = canResume(loadManifestState(dir, bvid), { plan: { ...PLAN, from: 60 } })
+  assert.equal(r.resumable, false)
+  assert.match(r.reason, /区间/)
+  assert.match(r.reason, /00:00-10:00/)
+})
+
+test('canResume：老 manifest 没记录 plan → 不敢按参数复用；只比区间时可以', (t) => {
+  const { dir, bvid } = makeState(t)
+  const st = loadManifestState(dir, bvid)
+  delete st.plan
+  saveManifest(dir, bvid, st)
+
+  const strict = canResume(loadManifestState(dir, bvid), { plan: { budget: PLAN.budget } })
+  assert.equal(strict.resumable, false)
+  assert.match(strict.reason, /没有记录 budget/)
+
+  // 老 state 没有 plan，但 range 还在：只给区间且与 range 一致 → 可以续
+  const loose = canResume(loadManifestState(dir, bvid), { plan: { from: 0, to: 600 } })
+  assert.equal(loose.resumable, true)
+  assert.equal(loose.doneGrids, 2)
+})
+
+test('canResume：没有 manifest / 没有拼图记录 → 不可复用', () => {
+  const missing = canResume(null)
+  assert.deepEqual(missing, { resumable: false, reason: '没有可复用的 manifest（这个视频还没跑过）', doneGrids: 0 })
+
+  const empty = canResume({ bvid: 'BVx', chunks: [] }, { plan: {} })
+  assert.equal(empty.resumable, false)
+  assert.match(empty.reason, /没有拼图记录/)
+})
+
+test('canResume：只给了 range 展示字符串的旧记录也能判断（按 duration 补齐区间）', (t) => {
+  const dir = tmpDir(t)
+  const sheet = writeSheet(dir, 'only.jpg')
+  const state = {
+    bvid: 'BVrange',
+    duration: 600,
+    plan: { budget: 1000 },
+    chunks: [{ chunk: 1, sheet, range: '00:00-10:00' }],
+  }
+  const r = canResume(state, { plan: { budget: 1000, from: 0, to: 600 } })
+  assert.equal(r.resumable, true)
+  assert.equal(r.doneGrids, 1)
+})
+
+test('recordStage / markDone：自动原子写回，重新 load 保持一致', (t) => {
+  const { dir, bvid } = makeState(t)
+  const st = loadManifestState(dir, bvid)
+
+  recordStage(st, 'grids', { done: 1, total: 2 })
+  assert.equal(loadManifestState(dir, bvid).stages.grids.status, 'running')
+
+  markDone(st, 'grids', { done: 2, total: 2 })
+  const again = loadManifestState(dir, bvid)
+  assert.equal(again.stages.download.status, 'done')   // 老记录不能丢
+  assert.equal(again.stages.grids.status, 'done')
+  assert.equal(again.stages.grids.done, 2)
+  assert.ok(again.stages.grids.doneAt)
+  assert.ok(again.updatedAt)
+
+  assert.deepEqual(fs.readdirSync(dir).filter((f) => f.endsWith('.tmp')), [])
+})
+
+test('recordStage：没有来源信息时只改内存、不写盘；非法参数抛 TypeError', () => {
+  const st = { bvid: 'BVx', stages: { download: 'done' } }
+  const out = recordStage(st, 'download', 'done')
+  assert.equal(out, st)
+  assert.equal(st.stages.download.status, 'done')
+  assert.match(st.stages.download.at, /^\d{4}-\d{2}-\d{2}T/)
+
+  assert.throws(() => recordStage(null, 'grids'), TypeError)
+  assert.throws(() => recordStage(st, ''), TypeError)
+})
+
+test('resumeSummary：列出阶段、拼图缺口、计划参数与可跳过项', (t) => {
+  const { dir, bvid, sheets } = makeState(t)
+  const st = loadManifestState(dir, bvid)
+  recordStage(st, 'grids', { done: 1, total: 2 })
+  fs.unlinkSync(sheets[1])
+
+  const s = resumeSummary(loadManifestState(dir, bvid))
+  assert.match(s, /BV1resume001/)
+  assert.match(s, /断点续跑测试片/)
+  assert.match(s, /阶段：下载 已完成 · 抽帧 进行中/)
+  assert.match(s, /拼图：1\/2 张可用/)
+  assert.match(s, /缺 1 张/)
+  assert.match(s, /计划：budget 20000 · density 6s/)
+  assert.match(s, /可跳过：下载/)
+  assert.match(resumeSummary(null), /没有 manifest/)
+})
+
+test('resumeSummary：拼图齐全时说明可跳过抽帧', (t) => {
+  const { dir, bvid } = makeState(t)
+  const st = loadManifestState(dir, bvid)
+  markDone(st, 'grids')
+  const s = resumeSummary(loadManifestState(dir, bvid))
+  assert.match(s, /拼图：2\/2 张可用（可跳过抽帧）/)
+  assert.match(s, /可跳过：下载、抽帧/)
+})

package/test/retry.test.mjs

@@ -0,0 +1,69 @@
+// retry 模块单测：可重试判定 + fetchWithRetry 行为（本地 mock server）
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import http from 'node:http'
+import { fetchWithRetry, isRetryableStatus, isTransientNetworkError } from '../lib/retry.mjs'
+
+test('isRetryableStatus：只重试 5xx / 429', () => {
+  assert.equal(isRetryableStatus(200), false)
+  assert.equal(isRetryableStatus(301), false)
+  assert.equal(isRetryableStatus(400), false)
+  assert.equal(isRetryableStatus(404), false)
+  assert.equal(isRetryableStatus(429), true)
+  assert.equal(isRetryableStatus(500), true)
+  assert.equal(isRetryableStatus(502), true)
+  assert.equal(isRetryableStatus(503), true)
+})
+
+test('isTransientNetworkError：网络错误可重试，其他不重试', () => {
+  assert.equal(isTransientNetworkError(new Error('fetch failed: ECONNRESET')), true)
+  assert.equal(isTransientNetworkError(new Error('socket hang up')), true)
+  assert.equal(isTransientNetworkError(new Error('ETIMEDOUT')), true)
+  assert.equal(isTransientNetworkError(new Error('something else')), false)
+  assert.equal(isTransientNetworkError(null), false)
+})
+
+test('fetchWithRetry：成功后直接返回（不发冗余请求）', async () => {
+  let hits = 0
+  const server = http.createServer((req, res) => { hits++; res.writeHead(200); res.end('ok') })
+  await new Promise((r) => server.listen(0, '127.0.0.1', r))
+  const port = server.address().port
+  try {
+    const res = await fetchWithRetry(`http://127.0.0.1:${port}/`, {}, { retries: 2, baseDelayMs: 10, quiet: true })
+    assert.equal(res.status, 200)
+    assert.equal(hits, 1)
+  } finally {
+    server.close()
+  }
+})
+
+test('fetchWithRetry：503 重试后成功', async () => {
+  let hits = 0
+  const server = http.createServer((req, res) => {
+    hits++
+    if (hits < 3) { res.writeHead(503); res.end('busy') } else { res.writeHead(200); res.end('ok') }
+  })
+  await new Promise((r) => server.listen(0, '127.0.0.1', r))
+  const port = server.address().port
+  try {
+    const res = await fetchWithRetry(`http://127.0.0.1:${port}/`, {}, { retries: 3, baseDelayMs: 10, quiet: true })
+    assert.equal(res.status, 200)
+    assert.equal(hits, 3)
+  } finally {
+    server.close()
+  }
+})
+
+test('fetchWithRetry：404 不重试', async () => {
+  let hits = 0
+  const server = http.createServer((req, res) => { hits++; res.writeHead(404); res.end('nope') })
+  await new Promise((r) => server.listen(0, '127.0.0.1', r))
+  const port = server.address().port
+  try {
+    const res = await fetchWithRetry(`http://127.0.0.1:${port}/`, {}, { retries: 3, baseDelayMs: 10, quiet: true })
+    assert.equal(res.status, 404)
+    assert.equal(hits, 1)
+  } finally {
+    server.close()
+  }
+})

package/test/ytdlp.test.mjs

@@ -0,0 +1,179 @@
+// ytdlp 模块单测：能力探测结构 / 二进制可用性 / URL 校验 / 失败兜底
+//
+// 这些测试不依赖「本机装没装 yt-dlp」：没装时 findYtdlp 返回 null、caps 报不可用，
+// 需要二进制的用例自动 skip。想跑真正的端到端下载（会联网、小文件）：
+//   FISHEYE_YTDLP_E2E=1 node --test test/
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { spawnSync } from 'node:child_process'
+import { downloadVideo, findYtdlp, ytdlpCaps } from '../lib/ytdlp.mjs'
+
+const CAP_KEYS = ['available', 'reason', 'summary', 'hint', 'cmd', 'ffmpeg', 'version', 'notes']
+
+/** caps 的公共结构断言（available / 不可用两种形态都适用） */
+function assertCapsShape(caps) {
+  for (const k of CAP_KEYS) assert.ok(k in caps, `caps 缺少字段 ${k}`)
+  assert.equal(typeof caps.available, 'boolean')
+  assert.equal(typeof caps.reason, 'string')
+  assert.ok(caps.reason.length > 0, 'reason 不能为空')
+  assert.equal(typeof caps.summary, 'string')
+  assert.match(caps.summary, /yt-dlp/)
+  assert.equal(caps.summary.includes(caps.available ? '可用' : '不可用'), true, 'summary 里要说明可用性')
+  assert.ok(caps.hint === null || typeof caps.hint === 'string')
+  assert.ok(caps.cmd === null || typeof caps.cmd === 'string')
+  assert.ok(caps.ffmpeg === null || typeof caps.ffmpeg === 'string')
+  assert.ok(Array.isArray(caps.notes))
+  if (caps.available) {
+    assert.equal(typeof caps.cmd, 'string', 'available 时必须给出 cmd')
+    assert.ok(caps.cmd.length > 0)
+  } else {
+    assert.ok(typeof caps.hint === 'string' && caps.hint.length > 0, '不可用时要给 hint')
+  }
+}
+
+/** 把 stdout+stderr 落到临时文件再读（沙箱里不能捕获管道） */
+function runCapture(cmd, args, timeoutMs = 20000) {
+  const file = path.join(os.tmpdir(), `fisheye-test-${process.pid}-${crypto.randomUUID().slice(0, 8)}.txt`)
+  let fd
+  let status
+  let error
+  try {
+    fd = fs.openSync(file, 'w')
+    const r = spawnSync(cmd, args, { stdio: ['ignore', fd, fd], timeout: timeoutMs, windowsHide: true })
+    status = r.status
+    error = r.error
+  } finally {
+    if (fd !== undefined) try { fs.closeSync(fd) } catch {}
+  }
+  try {
+    assert.equal(status, 0, `${path.basename(cmd)} ${args.join(' ')} 退出码 ${status}（${error?.message ?? '无错误信息'}）`)
+    return fs.readFileSync(file, 'utf8').replace(/^\uFEFF/, '')
+  } finally {
+    try { fs.unlinkSync(file) } catch {}
+  }
+}
+
+test('ytdlpCaps：结构完整，字段类型正确', () => {
+  const caps = ytdlpCaps()
+  assertCapsShape(caps)
+  // caps 与 findYtdlp 必须是同一个结论，不能一个说可用一个说没装
+  assert.equal(caps.available, findYtdlp() !== null)
+  // summaries 是给 CLI 打印的一行话，不该换行
+  assert.ok(!caps.summary.includes('\n'))
+})
+
+test('ytdlpCaps：可用时 reason 带版本与来源', () => {
+  const caps = ytdlpCaps({
+    ytdlp: { cmd: path.join(os.tmpdir(), 'yt-dlp.exe'), version: '2024.01.01', source: '单测注入' },
+  })
+  assertCapsShape(caps)
+  assert.equal(caps.available, true)
+  assert.match(caps.reason, /2024\.01\.01/)
+  assert.match(caps.reason, /单测注入/)
+  assert.equal(caps.version, '2024.01.01')
+})
+
+test('ytdlpCaps：不可用分支给出安装提示', () => {
+  // 直接喂一个空 ytdlp 会走真实探测；这里用伪造的环境 + 让所有候选都不存在不可行，
+  // 所以只断言：无 yt-dlp 时 hint 非空，有 yt-dlp 时 hint 为 null 或字符串。
+  const caps = ytdlpCaps({ env: { FISHEYE_YTDLP: 'C:\\definitely\\not\\here\\yt-dlp.exe' } })
+  assertCapsShape(caps)
+  if (!caps.available) assert.match(caps.hint, /yt-dlp\.exe|FISHEYE_YTDLP/)
+})
+
+test('findYtdlp：返回 null 或字段合法的对象', () => {
+  const f = findYtdlp()
+  if (f === null) return
+  assert.equal(typeof f.cmd, 'string')
+  assert.ok(f.cmd.length > 0)
+  assert.ok(f.ffmpeg === null || typeof f.ffmpeg === 'string')
+  if (f.ffmpeg) assert.ok(fs.existsSync(f.ffmpeg), `ffmpeg 路径不存在：${f.ffmpeg}`)
+  // cmd 是绝对/相对路径时必须真的存在；裸命令名（PATH 命中）允许
+  if (f.cmd.includes('/') || f.cmd.includes('\\')) assert.ok(fs.existsSync(f.cmd), `yt-dlp 路径不存在：${f.cmd}`)
+  assert.ok(f.version === null || /^\d{4}\.\d{2}\.\d{2}/.test(f.version))
+  assert.equal(typeof f.source, 'string')
+})
+
+test('findYtdlp：FISHEYE_YTDLP 指向不存在的文件时不崩', () => {
+  const f = findYtdlp({ env: { FISHEYE_YTDLP: 'C:\\definitely\\not\\here\\yt-dlp.exe' } })
+  assert.ok(f === null || typeof f.cmd === 'string')
+})
+
+test('yt-dlp 二进制能跑 --version（没装则 skip）', { skip: findYtdlp() === null }, () => {
+  const f = findYtdlp()
+  assert.ok(f && f.cmd)
+  const out = runCapture(f.cmd, ['--version'])
+  assert.match(out.trim(), /^\d{4}\.\d{2}\.\d{2}/)
+})
+
+test('ffmpeg 可用时能被解析出来（没装则 skip）', { skip: findYtdlp()?.ffmpeg == null }, () => {
+  const f = findYtdlp()
+  assert.ok(f?.ffmpeg)
+  assert.ok(fs.existsSync(f.ffmpeg))
+})
+
+test('downloadVideo：非法 URL 一律返回 null（不抛）', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'fisheye-ytdlp-bad-'))
+  const bad = [
+    '', '   ', 'not a url', 'ftp://example.com/v.mp4', 'javascript:alert(1)',
+    'file:///C:/Windows/win.ini', 'mailto:a@b.c', 'http://', null, undefined, 42, {},
+  ]
+  try {
+    for (const u of bad) {
+      const r = downloadVideo(u, dir, { quiet: true, timeoutMs: 5000 })
+      assert.equal(r, null, `非法 URL 应返回 null：${String(u)}`)
+    }
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+test('downloadVideo：没有输出目录时返回 null', () => {
+  assert.equal(downloadVideo('https://example.com/v', '', { quiet: true, timeoutMs: 5000 }), null)
+  assert.equal(downloadVideo('https://example.com/v', undefined, { quiet: true, timeoutMs: 5000 }), null)
+})
+
+test('downloadVideo：超时 → null（不抛）', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'fisheye-ytdlp-timeout-'))
+  try {
+    const r = downloadVideo('https://www.youtube.com/watch?v=BaW_jenozKc', dir, {
+      quiet: true,
+      timeoutMs: 500,
+    })
+    assert.equal(r, null)
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+// 可选端到端：默认跳过，FISHEYE_YTDLP_E2E=1 时下载 yt-dlp 官方 10 秒测试视频
+const E2E = process.env.FISHEYE_YTDLP_E2E === '1'
+
+test('downloadVideo：端到端下载官方测试视频', { skip: !E2E }, (t) => {
+  if (!findYtdlp()) {
+    t.skip('本机没有 yt-dlp')
+    return
+  }
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'fisheye-ytdlp-e2e-'))
+  try {
+    const r = downloadVideo('https://www.youtube.com/watch?v=BaW_jenozKc', dir, {
+      quiet: true,
+      timeoutMs: 180000,
+      quality: '480',
+    })
+    if (!r) {
+      t.skip('下载失败（网络 / 平台不可达），跳过端到端')
+      return
+    }
+    assert.ok(fs.existsSync(r.file), `返回的文件不存在：${r.file}`)
+    assert.ok(fs.statSync(r.file).size > 1024, '文件太小，可能不是视频')
+    assert.equal(path.dirname(r.file), dir)
+    assert.equal(typeof r.cmd, 'string')
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true })
+  }
+})