@missing-elements/h5p-verify
v1.6.0
Published
Plays an .h5p package in a headless browser through h5p-offline-player and reports whether it works: start-up, errors, missing libraries, a screenshot. The last check before a generated package is handed to anyone.
Maintainers
Readme
@missing-elements/h5p-verify
Plays an .h5p package in a headless browser through
h5p-offline-player and reports whether
it works. Needs Node 22 or later; write @latest, since without it npm on an older Node quietly
installs the last version that supported it.
npx @missing-elements/h5p-verify@latest course.h5ppass course.h5p ready in 0.37 s revision sha256:872ee6f732e6a4b7…
screenshot: course.verify/screenshot.pngfail course.h5p state error
bad-archive: This package contains no libraries, only content. … Missing: H5P.QuestionSet-1.21
fix: add the library folders (H5P.QuestionSet-1.21), or --libraries pack if the destination site supplies librariesExit code 0: it plays (possibly with warnings); 1: it does not; 2: the check could not run.
report.json and screenshot.png land in <package>.verify/.
It checks that the archive indexes and carries the libraries it declares, that the runtime
reaches ready, that nothing throws while booting (an error after ready is a warning), that the
content drew something, and it lists failed requests, CSP blocks, a video or audio the browser
could not play, and the build's revision. It does not judge correctness, suitability,
accessibility or licensing: look at the screenshot.
Played untrusted
A site that plays packages it did not make plays them
untrusted,
as the H5P plugins treat an upload: none of the package's own code runs, its libraries come only
from the site's pack, and its content is checked against each library's semantics.json.
--untrusted plays it that way:
npx @missing-elements/h5p-verify@latest course.h5p --untrustedpass course.h5p ready in 0.83 s revision sha256:c4fd49473b30cd97…
warning: content check: content[2].content.params.text: markup removed: <form>, <label> ×2, <input> ×2, <button>
warning: content check: content[3].content.params.text: attributes removed: style; style removed: display, padding, border-radius, background-color, color, text-decorationEach warning is a field the content will lose on such a site, measured by comparing the package's
content.json with what the runtime was handed. They are warnings because the content still plays.
A package built against a library newer than the pack is refused, with what to do. The libraries
come from the pack on jsDelivr unless --libraries names another; name a copy on disk, such as
node_modules/@missing-elements/h5p-libraries/parts, to run the check offline.
Preview
The check says whether a package starts. Whether it is right — the answers, a scenario's paths,
what happens at a video's timestamps — is for a person to judge, by playing it. --preview
checks nothing and opens the package in the real player in your browser, served from your
computer:
npx @missing-elements/h5p-verify@latest course.h5p --previewPreviewing course.h5p at http://127.0.0.1:4645/
The package stays on this computer. The preview ends when its tab is closed, or with Ctrl+C.It plays any content type the player plays, with the same player, runtime and library sources
as the check, so --untrusted, --libraries, --no-refresh-libraries and
--no-downgrade-libraries mean the same.
The package is served with Range, as a static host serves it. The libraries take a few
requests, and a video is read by the ranges the player asks for, so a large one starts at once
and nothing is read whole or extracted to disk.
The page has a Download button beside the package's name, so whoever reviews the package can keep the file they played.
The preview ends a few seconds after its last tab closes, so an agent can start it in the
background and leave it. --no-open prints the address instead of opening your default browser.
Exit code 0 when it ends, 2 when it could not start.
Options
| | |
|---|---|
| --preview | check nothing: open the package in the real player in your browser, served from your computer, until its tab is closed |
| --no-open | with --preview, print the address instead of opening a browser |
| --untrusted | play it as a site plays a package it did not make, and report what the content check removed |
| --libraries <sources> | where libraries come from, tried in order: pack (the library pack), a bundle's URL, a bundle on disk, or a copy of the pack's parts/ folder, which plays as pack; the verifier serves what is on disk itself. With the pack, a library the package carries plays at the pack's newer version, as on a site with the pack, and the summary lists each under refreshed from the pack |
| --no-refresh-libraries | play the libraries the package carries even where the pack has newer ones |
| --no-downgrade-libraries | fail content made for a newer minor version of a library than any source has. Without it, such content plays at the newest older minor, as on a site with the player's defaults, with a warning for each library and the list in report.downgraded |
| --out <dir> | where the report and screenshot go |
| --browser <path> | a Chromium-based browser; otherwise Chrome, then Edge, then Playwright's Chromium |
| --ready <s> | time allowed to reach ready, default 60 |
| --settle <s> | time watched after ready for late errors, default 3 |
| --json | the report as JSON on stdout |
| -q, --quiet | the verdict line only |
| -h, --help | |
Needs Node 22 or later and a Chromium-based browser; without Chrome or Edge, run
npx playwright install chromium.
From code
import { verifyPackage, summarize } from '@missing-elements/h5p-verify'
const report = await verifyPackage({ file: 'course.h5p', out: 'report/', untrusted: true })
console.log(summarize(report))
if (report.verdict !== 'pass') process.exit(1)TypeScript declarations ship with the package: VerifyReport is report.json's shape.
previewPackage({ file, libraries, untrusted }) serves the preview as --preview does and gives
its url, close(), and a closed promise that settles with closed once its last tab has gone,
unopened when no tab came within ten minutes, or stopped after close(). openBrowser(url)
opens an address in the default browser, false where no opener started.
An agent skill for it ships in the repository:
npx skills add missing-elements/h5p-offline-player --skill h5p-verify.
Licence
MIT. It runs the player, whose H5P runtime is GPL-3.0; see the player's NOTICE.md.
