ArtPlayer/test/README.md

# Tests and fixture ownership

`test/multiple-subtitles-ass.test.js` verifies hashes of actual core5.1.2 main,
legacy and source before comparing conversion behavior. It covers the collapsed
main output, source-equivalent timings/text, valid/custom/empty passthrough and
converter failure cleanup through the real candidate plugin. It runs in both
`test:unit` and `test:multiple-subtitles`. This is native VTT conversion, not ASS
layout/rendering acceptance for JASSUB.

`test/multiple-subtitles-caption.test.js` checks the old-host view adapter with the
actual plugin bundle: native order, original update identity/scalar event payload,
escape changes, timestamp cleanup, modern-host isolation and destroy/registration
failure cleanup. It runs in `test:unit` and `test:multiple-subtitles`, without new
dependencies. Native cue timing is separately verified in the browser suite.

`test/multiple-subtitles-entities.test.js` checks named entities, literal tags,
double encoding, nested semantic tags and selection/reset through the real plugin.
The vendor parity suite stays unchanged: the plugin uses the parser's existing
entity-table option. Historical malformed-tag and stray-semicolon tests continue
to assert old defects; corrected cases have explicit rendering expectations instead
of treating those old serialized bytes as a required contract. Browser entity
tests compare native VTT fragments and actual HTML captions on both core variants.

`yarn test:library` runs actual library builds, build-input freshness checks and the
scaffold's generated consumers. The new build modules live in `scripts/library/`;
`yarn typecheck:library` checks them and the retained JS/MJS entrypoints. Browser
development/watch/error-recovery coverage is `browser/library-development.spec.js`.

`yarn test:dev-server` covers actual HTTP ranges/HEAD/gzip, root containment,
occupied-port CLI failure without stopping the existing server, repeated same-port
reuse with SSE connections, aborted downloads and startup/build cancellation.
A controlled-clock test checks heartbeat cleanup separately from real sockets.
It is included in `test:node` and `test:library`; the browser suite also verifies
actual docs/Monaco TypeScript execution and local media playback through this server.

`yarn test:scaffold` covers old plugin-generator defects, exclusive writes and
rollback, the historical CLI path, and actual generated package builds and type
consumers. It runs in ignored fixtures without adding a workspace or real demo;
see `scripts/plugin/README.md`. `yarn typecheck:scaffold` checks its TS modules and
JS command shim. Both are wired into the existing Node/CI checks.

`site-loading.test.js` freezes the old mobile loader's failure/race reproduction
and checks shared loader ownership, retries/cancellation, query encoding and
language rules. Actual local pages and Monaco are covered by site-loading.spec.js.

Editor tooling lives in `scripts/editor-declarations/`; see its README.
`test/editor-types.test.js` checks standalone globals and module consumers with
current/old compilers, Chapter/VAST regressions, generated files and library-list
failures. Package baseline tests continue to exercise the old MJS import paths.

Use the pinned Node/Yarn toolchain from `../refactor/toolchain-setup.md`.

`yarn build:test` generates deterministic documentation readiness smoke and its
source manifest. `yarn check:docs-smoke` is read-only, and
`yarn typecheck:docs-tools` checks the TS modules and legacy JS command shim.
`refactor/scripts/docs-smoke.test.mjs` covers the historical malformed-parser loop,
all 233 current source snippets, stable generation and CLI drift/error handling.
`test/browser/docs-smoke.spec.js` uses actual core/media in three engines for
readiness, failures, frame cleanup, storage restoration and repeated execution.
See `scripts/docs-smoke/README.md` for the explicit limits of readiness smoke.

`yarn test:vue-consumer` checks the actual Vue example with packed core/Danmuku/
Document PiP in an outside-workspace install. It also installs its pinned Vue
compiler there, checks all declaration paths for isolation, and runs development
and production builds in three engines. `test/vue/` contains strict SFC/type
fixtures and a separate plain-JS consumer. Reports under
`refactor/.cache/vue-consumer-*` cover updates, remount, KeepAlive, captured errors,
native media and real Worker cleanup. `--before` substitutes the recorded old
wrapper and must preserve the same lifecycle behavior; it is not expected to fail.

`yarn test:react-consumer` installs packed core/Danmuku/Document PiP outside the
workspace and checks the actual React example's strict TSX, development and
production builds, and native lifecycle/playback in three engines. Its fixture
is in `test/react/`; unique reports and frozen consumer locks are retained under
`refactor/.cache/react-consumer-*`. The `--before` control intentionally fails at
the recorded old wrapper's callback-exception leak. See the example README for
the compatibility contract and the capabilities covered by other package tasks.

`test/auto-thumbnail-encoding.test.js` verifies a separate30-second JPEG deadline,
withheld and duplicate callbacks, replacement/destruction, synchronous completion
and timer cleanup failures. It runs in `test:auto-thumbnail` and `test:unit`.
Native lifecycle tests deliberately hold an actual JPEG callback and invoke the
captured deadline; that proves cleanup with native resources, not a spontaneous
encoder hang. First-frame pixel and device limitations remain separate gates.

`yarn test:auto-thumbnail-types` checks the preserved npm 1.1.0 declaration,
accurate `/runtime` Promise types, exact rejected consumer lines, and generated
editor globals. It also runs in `test:auto-thumbnail` and `test:baseline`.
`yarn test:auto-thumbnail-types-package` packs the candidate and installs it and
the actual npm 1.1.0 archive outside the workspace with a packed core. It verifies
frozen reinstalls, byte identity, conditional declaration resolution, old/current
compiler consumers, no-interop CommonJS, and installed factory registration.
It also installs actual 1.0.1 to verify old `.default` calls and confirms 1.0.0's
missing main/legacy artifacts. Candidate direct/default calls share a callable;
runtime types describe the alias without changing the historical root declaration.
This does not decode video or close all older type-shape, native pixel, or device
acceptance gaps. Candidate entry types use the same runtime files.

`yarn probe:auto-thumbnail-rendering` is an optional diagnosis command, separate
from passing test suites. It runs four intrinsic-size rendering modes and three
readiness strategies in Windows WebKit, plus Chromium/Firefox controls. It records
raw draw pixels, seek/event ordering, frame counters and exact code/media hashes
in a new cache directory. Completion of the command does not imply correct pixels:
the current WebKit first-frame discrepancy remains an open release/refactor risk.

`yarn test:danmuku-mask` runs candidate run cancellation/resource ownership plus
frozen historical defects and public contracts. Candidate tests also run in
`test:unit`; their controlled SDK, RAF and canvas hosts do not prove native model
inference, GPU disposal or browser mask geometry. See the Mask architecture map.
`yarn test:danmuku-mask-types-package` installs both published versions and the
candidate tarball outside the workspace for old/current compiler compatibility,
negative cases and CJS/legacy registration without model startup. The ordinary
baseline suite also checks public declaration identity and editor generation.

`yarn test:mediabunny` runs historical lifecycle observations, candidate load cancellation,
and real SDK input parsing/track contracts; all are in `test:unit`. Candidate failures
can be reproduced against the frozen main with `ARTPLAYER_MB_BASELINE=1`. This does not
replace native playback or installed consumers. See `refactor/mb-validation.md` and the
proxy package's `ARCHITECTURE.md` for browser and artifact selection.

`yarn test:ads` runs source, verified npm 1.0.6 and the frozen unpublished 2.1.0
Ads bundle against controlled clock/host contracts. It is included in `test:unit`.
The helper uses the real option validator but does not simulate media decoding or layout.
Historical defect assertions apply only to frozen implementations. See
[Ads validation](../refactor/ads-validation.md) for artifact overrides and browser scope.
`ads-lifecycle.test.js` adds candidate-only resource, reentry, early-method and Promise
regressions. Async observations drain one event-loop turn, including VM Promise assimilation,
rather than assuming a fixed number of microtasks. The published defect observations stay intact.

| Command             | Scope                                                                                                    |
| ------------------- | -------------------------------------------------------------------------------------------------------- |
| `yarn test:unit`    | Playback and DASH regressions, public contracts against released/current code, and JS/TS fixture loading |
| `yarn test:node`    | Unit contracts plus toolchain and documentation build failure propagation                                |
| `yarn test:ci`      | Actual CI summary exit codes, workflow regression guards and repository impact analysis                  |
| `yarn test`         | Node checks and the committed baseline/tooling tests in refactor/scripts                                 |
| `yarn ci:check`     | Toolchain, plan, read-only lint, types, then yarn test                                                   |
| `yarn test:imports` | Existing distribution import smoke examples; run after building                                          |

`helpers/load.js` owns source and artifact selection. `loadModules` bundles named internal modules with esbuild and requires exactly one JS/TS source file. `loadPackage` uses the repository Vite configuration without writing distribution files; it requires a single self-contained JavaScript chunk. These loaders transpile but do not replace `yarn typecheck`.

`helpers/playback.js` creates the controlled media facade used by the original playback regressions. It models only the exercised methods and events. It is not HTMLMediaElement validation; actual playback remains in browser tests.

`node --test test/hls-control.test.js` runs shared HLS control contracts against workspace source
and integrity-checked published main/legacy/ESM. It is included in `yarn test:unit`.
`helpers/hls-control.js` owns the controlled SDK/registry host; it does not simulate decoding or ABR.
Published-only tests preserve historical bug observations without requiring candidate code to keep them.
Real Hls.js 1.5.17 playback is in `test/browser/hls-control.spec.js`; see its environment limits in
`refactor/hls-validation.md`. Test SDK download is pinned and verified, not an installed runtime dependency.

`contracts/emitter.js` owns public assertions, independent of module layout. `public-behavior.test.js` runs them against the integrity-checked published core and current bundled source. The combined chain/context contract corresponds to BASE-03 EVENT.chain and EVENT.context-arguments; other EVENT IDs retain their baseline names. Exceptions, callback identity, mutation during dispatch and once reentry must not be weakened during migration.

Set `ARTPLAYER_TEST_CORE` to a built `.js`, `.legacy.js` or `.mjs` core file to add a candidate to the same public-contract run, then execute `node --test test/public-behavior.test.js`. An invalid path/export fails the run. This is a narrow event contract check, not isolated package installation or complete API compatibility; ENG-07 owns tarball consumption.

When a production module moves, update its loader mapping and its maintenance documentation, preserving the behavioral assertions. New contracts belong in contracts/; test-specific controlled state belongs in helpers/. Do not modify frozen refactor/fixtures or baseline captures just to pass changed behavior. Record historical defects and candidate fixes separately.

`ci-summary.test.js` exercises the real CLI with success, cancelled and malformed provider data,
plus missing groups and metadata/environment files. It is included in `test:node`.
`refactor/scripts/ci-workflow.test.mjs` parses the actual YAML and rejects broken matrix,
cache, install, report and summary requirements; it is included in `test:baseline`.
These local tests do not replace hosted runner or branch-protection evidence.
See [CI operations](../refactor/ci-setup.md) before changing a required job or its cache.

# Real browser tests

`test/utils.test.js` compares the published and current utilities, including exact formatting,
subtitle text, property/merge behavior, controlled timers and the full utility export surface.
It accepts the same `ARTPLAYER_TEST_CORE` option for all three artifact formats. The merge
prototype fix is a candidate assertion alongside a published-only defect observation.
`test/types/utils-source.ts` checks strict internal source inference without changing the
still-separate public declaration contract. Browser utility tests exercise actual downloads,
Blob URL contents and cleanup when a controlled click fails.

See [browser/README.md](browser/README.md) for `yarn test:browser`, browser installation,
published/current combinations, media fixtures, candidate mapping and failure reports.
These tests are separate from the fast Node suite and run in the Browser playback smoke CI job.

`test/audio-track.test.js` compares source and published Audio Track 1.1.0 in all three
formats with a controlled Audio object: timing intent, offsets, source updates, rejection,
volume/rate, independent instances and cleanup. Published-only tests retain defect evidence.
See [audio validation](../refactor/audio-validation.md) for actual media tests and limitations.

Document PiP: `yarn test:dpip` runs 48 historical window/DOM/lifecycle cases. Native DOM iframe checks use `yarn test:browser test/browser/dpip.spec.js`; controlled window APIs do not establish native Document PiP support. See [validation notes](../refactor/dpip-validation.md).

Danmuku: `yarn test:danmuku` covers historical behavior and current input, scheduling,
settings, rendering and heatmap boundaries. `ARTPLAYER_DANMUKU_ARTIFACT` selects a
built main/legacy candidate for integration cases; direct internal tests remain
source tests. This controlled synchronous VM loader executes CommonJS/UMD scripts,
not `.mjs` modules. Do not pass ESM bytes to that override or interpret its parser
failure as a production ESM failure. Actual ESM imports are checked by the isolated
package consumer; full native distribution coverage remains the package release gate.
The candidate Worker helper executes the selected artifact's Blob or data URL bytes;
only source-mode controlled imports compile `worker.ts` separately. The frozen
published helper remains unchanged. `yarn test:danmuku-types` checks the unchanged
npm root, the optional accurate `/runtime` entry, implementation assignability and
semantic editor declarations. `yarn test:danmuku-types-package` packs and installs
the packages outside the workspace, verifies exact member bytes and frozen offline
reinstallation, and checks historical and current compiler consumers. These type
checks do not replace the native browser suite or final distribution acceptance.

## Documentation pipeline regressions

`node --test test/documentation-pipeline.test.js` covers the frozen old translator's
delete-before-request, broken fence repair and exhausted 429 behavior; the new
draft workflow checks failure, worker cancellation/join, reviewed apply, stale
inputs, path escape, rollback and concurrent edits. Existing source Markdown
round-trips and the offline source corpus are checked against actual inputs.
A loopback HTTP server verifies a stalled response body times out. Mock responses
test bounded retries and invalid data; no paid translation is performed and these
tests do not certify English prose quality. Included in `test:node`.

## Site build regressions

`yarn test:site-build` covers i18n compile failure, staged replacement and rollback,
concurrent build/output conflicts, retained backups, actual language dictionaries
and globals in four module modes, and a real Yarn documentation fixture child.
Use this Yarn script instead of `yarn node`, which does not supply the lifecycle
environment used to locate the pinned Yarn executable. The Markdown test uses
the installed VitePress renderer to reproduce random code-group IDs and verify
stable IDs, uniqueness and label associations. Built-page browser checks live in
`test/browser/document-site.spec.js`; their editor destination is intercepted.

## Desktop editor regressions

`yarn test:site-editor` covers frozen old TS execution/file error behavior, latest-run
ordering, library/compiler failures, FileReader settlement and storage denial.
`test/browser/site-editor.spec.js` uses the actual Monaco 0.30.1 worker and original
vendor assets for typed Run, Ctrl-S, imports, preferences, declaration failure,
language readiness and model disposal. Console Error objects are inspected through
their arguments: Firefox may serialize their display text as only `Error`.

## Multiple subtitles core combinations

`test/browser/multiple-subtitles-combinations.spec.js` uses verified old core and
plugin bytes plus candidate source builds. It covers native caption timing,
VTT/SRT selection, offsets/fullscreen/source changes and multi-instance URL
ownership. Old1.0.0/1.1.0/1.2.0 factories run unchanged on the candidate core.
Explicit single-active-cue probes record historical and candidate overlap defects;
their passing assertions do not mean simultaneous captions are compatible.
Candidate paused Firefox offsets are corrected by CORE-SUBTITLE-OFFSET-01. Old
Firefox hosts retain explicit defect observations; their behavior is not silently
counted as correct. Task09 classified the apparent WebKit source-switch caption
loss as an old-host seek landing near zero, reproducible without any plugin.
See `refactor/changes/2026-09-14-PKG-MULTI-SUB-05-combinations.md` before changing
expectations. Reports include native active cues and rendered text. The new frozen
5.1.2 core route verifies archive integrity and member hashes before serving.

`subtitle-offset.spec.js` checks current/actual published core offset behavior,
including synchronous native/public/rendered captions, identical cue objects,
unchanged media time, disabled mode and resumed playback. The published Firefox
branch asserts the original incorrect captions; the candidate must have the correct
membership and order. `subtitle-offset-native.spec.js` loads a real HTML track
without creating an Artplayer instance to compare native timing edits, cue
reinsertion and mode toggling. It records actual time within the required interval,
not a fabricated millisecond-exact seek landing. These diagnostic observations
do not claim every native engine strategy is correct.

`multiple-subtitles-switch.spec.js` records source Promise settlement, native
currentTime writes/events and actual seek landing with no plugin, candidate and
published1.2.0. Old first-seek misses are retained as observations; every candidate
first seek must land. The caption combination fixture separately waits for native
source seeking to finish and for fullscreen-enter notification before testing
subsequent commands. It retains exact caption and enter/exit order assertions;
do not add delays or plugin retries to cover old core readiness behavior.