mirror of
https://github.com/zhw2590582/ArtPlayer.git
synced 2026-10-09 03:46:16 -08:00
76 lines
4.9 KiB
Markdown
76 lines
4.9 KiB
Markdown
# Documentation readiness smoke
|
|
|
|
This generator keeps the existing `yarn build:test` / `node scripts/build-test.js`
|
|
entrypoint and `docs/test/test.js` URL. Use the pinned Node 24.21.0 runtime and
|
|
Yarn 1.22.22. Node runs the owned TypeScript modules using native type stripping;
|
|
the command shim remains JavaScript and is included in strict `checkJs` checking.
|
|
The root typecheck commands use `node node_modules/typescript/bin/tsc` explicitly:
|
|
Yarn's shared `tsc` binary can point at the installed 5.1.6 compatibility alias.
|
|
The main 5.9.3 compiler and older compatibility compilers retain distinct roles.
|
|
|
|
| File | Ownership |
|
|
| ----------------------- | ---------------------------------------------------------------------------------------------------------- |
|
|
| `parser.ts` | Markdown tokens, Run Code/fence adjacency, source locations and closing fences |
|
|
| `generator.ts` | Deterministic file discovery, syntax compilation without execution, dependency list and browser bundle |
|
|
| `runtime.ts` | One sequential example frame, script loading, error/readiness observation, teardown and Mocha registration |
|
|
| `../build-test.js` | Original CLI path, argument validation and write/read-only check |
|
|
| `../tsconfig.docs.json` | Strict Node/DOM tools check, including the JavaScript shim |
|
|
|
|
```sh
|
|
yarn build:test
|
|
yarn check:docs-smoke
|
|
yarn typecheck:docs-tools
|
|
node --test refactor/scripts/docs-smoke.test.mjs
|
|
yarn test:browser test/browser/docs-smoke.spec.js
|
|
```
|
|
|
|
`docs/test/examples.json` records stable source file/line IDs, original code and
|
|
the ordered script list from `docs/test/index.html`. No timestamps enter generated
|
|
content. Generation validates every selected example before writing either output;
|
|
`--check` compares both files without modifying them. Parse/syntax errors fail the
|
|
command with a source location. This is not a transactional multi-file filesystem
|
|
write if the filesystem itself fails during output.
|
|
|
|
The scope stays Chinese JavaScript fences after Run Code markers, excluding
|
|
`en`, `plugin`, `public` and `.vitepress`. There are 233 current cases in 11 files.
|
|
CRLF is normalized to LF. New cases must be reviewed and the deliberate count
|
|
assertion updated. JS syntax compilation does not execute snippets or validate
|
|
their API semantics. TypeScript/editor declaration generation remains SITE-02.
|
|
|
|
The browser bundle registers cases with the existing Mocha BDD page. Each case:
|
|
|
|
1. Creates an iframe with its own ArtPlayer container and loads the page's runtime
|
|
scripts in order, excluding Mocha, Chai and the generated test script itself.
|
|
2. Evaluates the snippet as a classic script in that frame, awaits its returned
|
|
promise if any, and waits for the currently created players' `ready` events.
|
|
3. Observes thrown errors, unhandled rejections and media/player errors until that
|
|
readiness boundary plus one task turn. A 4500 ms deadline produces failure,
|
|
never success. Cases without players cover evaluation only.
|
|
4. Detaches observer listeners, destroys frame players, removes the iframe and
|
|
restores local/session storage. Cleanup errors are failures and retain an
|
|
earlier failure in the error list. Concurrent calls are rejected.
|
|
|
|
The iframe is an owned browsing context, **not a security sandbox**. It shares
|
|
the parent origin. Run the test page on an isolated test origin with no concurrent
|
|
same-origin work: storage restoration does not merge writes from other tabs.
|
|
Unchanged browser storage is restored after each case, while frame-owned timers
|
|
and globals disappear when the frame is removed. Arbitrary external resources
|
|
that a snippet deliberately hands to another window are outside this ownership.
|
|
|
|
Readiness is not playback, interaction or complete asynchronous feature acceptance.
|
|
Delayed actions scheduled after this boundary are not verified; examples involving
|
|
clicks, seek, SDKs, windows and full lifecycle behavior remain EX-03/package tests.
|
|
The automated harness tests use actual core/media and three selected unchanged
|
|
documentation snippets with controlled media. They do not certify all 233 examples
|
|
or the remote SDK endpoints in the full manual page.
|
|
|
|
Windows WebKit has the existing DPIP-MEDIA-01 dimension discrepancy: the same
|
|
320x180 media can report 640x360 layout dimensions. The harness retains exact raw
|
|
readings and only these documented pairs; it does not close intrinsic-size or
|
|
real Safari/device acceptance. See `refactor/site-inventory.md` for broader ownership.
|
|
|
|
Dependencies: root development-only `@types/node` 24.10.0 and
|
|
`@types/markdown-it` 14.1.2 provide strict tools typing. Runtime parsing uses the
|
|
existing MarkdownIt 14.1.0 and browser bundling uses the existing pinned esbuild.
|
|
No player package runtime dependency changes.
|