@vestra-player/sdk 1.5.31 → 1.5.33

package/dist/plugin/testing.js

@@ -307,6 +307,19 @@ const MAX_SIDEBAR_TABS = 8;
  *   await stop();
  * });
  * ```
+ *
+ * @remarks
+ * An in-memory player that speaks the real wire protocol, so the SDK's own
+ * logic runs as it does in the player; only the player side is simulated
+ * (no decoding, no Slint, no windows). Make one per test, preset it if the
+ * plugin reads something during activation, start the plugin with
+ * {@link startPlugin}, drive it, `settle()`, and assert on what it
+ * recorded.
+ *
+ * @capability None.
+ * @see [Test a plugin](../../docs/how-to/testing.md)
+ * @since 1.0.0
+ * @category Testing
  */
 export class TestHost {
     /**
@@ -416,6 +429,20 @@ export class TestHost {
      *
      * @param directory - The package directory (holding `locales/`).
      * @since 1.5.9
+     *
+     * @capability None.
+     *
+     * @example Load the translations after changing the language
+     * The test switches the host to German before starting the plugin and
+     * loads that catalog itself (`startPlugin` does the same). Texts are then
+     * shown in German.
+     * ```ts
+     * declare const host: TestHost;
+     * declare const directory: string;
+     * // ---cut---
+     * host.locale = "de";
+     * host.loadCatalog(directory); // locales/de.po (or de.json)
+     * ```
      */
     loadCatalog(directory) {
         this.#catalog = loadPackageCatalog(directory, this.locale);
@@ -441,6 +468,8 @@ export class TestHost {
      * ```
      *
      * @since 1.5.9
+     *
+     * @capability None.
      */
     translate(text, args) {
         if (typeof text !== "string")
@@ -520,6 +549,24 @@ export class TestHost {
      *
      * @param language - `"system"` or a locale.
      * @since 1.5.9
+     *
+     * @capability None.
+     *
+     * @example Simulate the user choosing French for the next start
+     * The plugin hears that the saved interface language changed. The host
+     * pushes `appearance.changed`, which a plugin with `events` sees in
+     * `appearance.language` once it has read it and subscribed; this run's
+     * language does not change.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * void plugin.appearance.language; // read once: the SDK then follows it
+     * plugin.appearance.onChange(() => {}); // subscribes to appearance events
+     * host.setLanguage("fr");
+     * await host.settle();
+     * assert.equal(plugin.appearance.language, "fr");
+     * ```
      */
     setLanguage(language) {
         this.language = language;
@@ -713,6 +760,9 @@ export class TestHost {
      * await host.settle();
      * assert.equal(plugin.timeline.marks.length, 2);
      * ```
+     *
+     * @capability None.
+     * @since 1.0.0
      */
     setTimelineLayer(pluginId, marks) {
         if (marks.length)
@@ -755,6 +805,9 @@ export class TestHost {
      *   join(plugin.dataDirectory, "cover.png"),
      * );
      * ```
+     *
+     * @capability None.
+     * @since 1.0.0
      */
     imagePath(value) {
         const image = value;
@@ -865,6 +918,10 @@ export class TestHost {
      *   modifiers: { alt: true },
      * });
      * ```
+     *
+     * @capability None.
+     * @throws Never: files nobody takes are ignored, as in the player.
+     * @since 1.0.0
      */
     drop(paths, options = {}) {
         const modifiers = {
@@ -899,6 +956,24 @@ export class TestHost {
     /**
      * Simulate another plugin switching the palette: updates
      * {@link TestHost.appearance} and pushes `appearance.changed`.
+     *
+     * @capability None.
+     *
+     * @example Simulate another plugin switching to the light palette
+     * The plugin hears the palette change. The host updates `appearance` and
+     * pushes `appearance.changed` to a plugin that listens with `events`.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * const themes: ThemeId[] = [];
+     * plugin.appearance.onChange((theme) => themes.push(theme)); // subscribes (`events`)
+     * host.setAppearance("vestra-light");
+     * await host.settle();
+     * assert.deepEqual(themes, ["vestra-light"]);
+     * ```
+     *
+     * @since 1.0.0
      */
     setAppearance(theme) {
         this.appearance = theme;
@@ -935,6 +1010,9 @@ export class TestHost {
      * await host.settle();
      * assert.equal(page.props["step"], 10);
      * ```
+     *
+     * @capability None.
+     * @since 1.0.0
      */
     settingsPage(id) {
         const page = this.settings.pages.get(id);
@@ -947,6 +1025,23 @@ export class TestHost {
     /**
      * Simulate the backdrop's `effective` changing (`false`: a video frame
      * appeared; `true`: there is none again); pushed to the plugin.
+     *
+     * @capability None.
+     *
+     * @example Make a video picture replace the backdrop
+     * The plugin's backdrop hears that a video frame now covers it. `false`
+     * means a picture appeared; the change is pushed like the player's
+     * `window.state`.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * host.setBackdropEffective(false);
+     * await host.settle();
+     * assert.equal(plugin.panels.backdrop.state?.effective, false);
+     * ```
+     *
+     * @since 1.0.0
      */
     setBackdropEffective(effective) {
         if (this.backdrop)
@@ -986,6 +1081,8 @@ export class TestHost {
      * ```
      *
      * @since 1.5.2
+     *
+     * @capability None.
      */
     mountOther(slot, plugin, options = {}) {
         if (this.#others.has(plugin))
@@ -1009,6 +1106,21 @@ export class TestHost {
      * when its tab was current, the next tab (else the previous one) is.
      *
      * @since 1.5.2
+     *
+     * @capability None.
+     *
+     * @example Let the playlist's tab go away
+     * The other plugin's sidebar tab disappears and the plugin's own tab
+     * becomes current. When the removed tab was current, the next tab (else
+     * the previous one) becomes current, as in the player.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * host.unmountOther("vestra.playlist");
+     * await host.settle();
+     * assert.equal(host.layout.sidebar?.panels?.length, 1);
+     * ```
      */
     unmountOther(plugin) {
         const other = this.#others.get(plugin);
@@ -1027,6 +1139,20 @@ export class TestHost {
      * becomes the current tab. Pushed as a `window.state` change.
      *
      * @since 1.5.2
+     *
+     * @capability None.
+     *
+     * @example Click another plugin's sidebar tab
+     * The user switches the sidebar to the playlist; the plugin's panel is in
+     * a background tab now. The change is pushed as `window.state`.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * host.selectTab("vestra.playlist");
+     * await host.settle();
+     * assert.notEqual(host.layout.sidebar?.owner, 1); // the plugin under test is owner 1
+     * ```
      */
     selectTab(plugin) {
         const slot = this.layout.sidebar;
@@ -1077,6 +1203,24 @@ export class TestHost {
      * Simulate another plugin taking the display layer first (the plugin's
      * `video.view()` then fails with `conflict`), or, with `null`, releasing
      * it (values reset to the defaults).
+     *
+     * @capability None.
+     *
+     * @example Let another plugin own the display layer
+     * The plugin's `video.view()` fails with `conflict` because another plugin
+     * took the display layer first. `null` releases it again.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * host.setVideoViewOwner("someone.zoom");
+     * const view = plugin.video.view();
+     * view.set({ zoom: 2 });
+     * await host.settle();
+     * assert.equal(view.status.state, "failed");
+     * ```
+     *
+     * @since 1.0.0
      */
     setVideoViewOwner(pluginId) {
         this.videoView.owner = pluginId;
@@ -1093,6 +1237,24 @@ export class TestHost {
      * Simulate another plugin owning the render options (the plugin's
      * `video.render()` then fails with `conflict`), or, with `null`, releasing
      * them (values reset to the defaults).
+     *
+     * @capability None.
+     *
+     * @example Let another plugin own the render options
+     * The plugin's render options report `conflict` while another plugin owns
+     * them; `null` releases them and resets the values to the defaults.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * host.setVideoRenderOwner("someone.hdr");
+     * const render = plugin.video.render();
+     * render.set({ toneMapping: "bt.2390" });
+     * await host.settle();
+     * assert.equal(render.status.state, "failed");
+     * ```
+     *
+     * @since 1.0.0
      */
     setVideoRenderOwner(pluginId) {
         this.videoRender.owner = pluginId;
@@ -1120,6 +1282,9 @@ export class TestHost {
      * await host.settle();
      * assert.equal(render.status.state, "failed");
      * ```
+     *
+     * @capability None.
+     * @since 1.0.0
      */
     failVideoRender(code, message) {
         if (code === "unsupported")
@@ -1213,6 +1378,21 @@ export class TestHost {
      * What `plugin.resolvers.fileTypes` reports: the extensions of this
      * plugin's file resolvers and of {@link TestHost.otherResolvers}, sorted,
      * each once.
+     *
+     * @capability None.
+     *
+     * @example Check the file types a resolver adds
+     * The test checks the list the plugin will read as
+     * `resolvers.fileTypes`: the extensions of its own file resolvers and of
+     * `otherResolvers`, sorted, each once.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * assert.deepEqual(host.fileTypes(), ["ch8"]);
+     * ```
+     *
+     * @since 1.5.8
      */
     fileTypes() {
         const types = new Set();
@@ -1245,6 +1425,9 @@ export class TestHost {
      * await host.settle();
      * assert.deepEqual(plugin.resolvers.fileTypes, ["ch8"]);
      * ```
+     *
+     * @capability None.
+     * @since 1.5.8
      */
     updateFileTypes() {
         const types = this.fileTypes();
@@ -1393,6 +1576,11 @@ export class TestHost {
      * `"test.plugin"` by default).
      */
     manifestId = "test.plugin";
+    /**
+     * A fresh in-memory player: nothing open, no plugin, the player's core
+     * actions registered. Preset what the plugin reads during activation, then
+     * pass it to {@link startPlugin} as `host`.
+     */
     constructor() {
         this.subtitles = {
             presentation: {
@@ -1481,8 +1669,10 @@ export class TestHost {
     /**
      * One of the 14 core actions (`play-pause`, `stop`, `seek-forward`, ...)
      * that the test host registers like the player, as `host/<id>`. Throws for
-     * an unknown id. `run()` executes it with the player's checks and writes
-     * its on-screen text to {@link TestHost.osd}.
+     * an unknown id. `run()` executes it like its menu item: a disabled
+     * action rejects with `command`, as in the player (`plugin.host.run`
+     * rejects with `unavailable` instead); otherwise it runs with the
+     * player's checks and writes its on-screen text to {@link TestHost.osd}.
      *
      * @example Pause through the player's own action
      * The test pauses playback the way the Space key does and checks that the
@@ -1498,6 +1688,9 @@ export class TestHost {
      * assert.equal(host.source.paused, true);
      * assert.deepEqual(host.coreRuns, ["play-pause"]);
      * ```
+     *
+     * @capability None.
+     * @since 1.0.0
      */
     coreAction(id) {
         const command = this.coreCommands.get(`host/${id}`);
@@ -1703,6 +1896,10 @@ export class TestHost {
                 set state(_value) { },
                 revision: 1,
                 async run() {
+                    // Like the player's menu: a disabled or busy command does not run.
+                    const state = host.#coreState(id);
+                    if (state.busy || !state.enabled)
+                        throw new HostError("command", `host/${id} is ${state.busy ? "busy" : "disabled"}`);
                     await host.request("host.run", { action: id });
                     await host.settle();
                 },
@@ -1879,11 +2076,36 @@ export class TestHost {
      * assert.deepEqual(host.osd, ["Folder not found"]);
      * host.reset("system.openPath");
      * ```
+     *
+     * @capability None.
+     * @since 1.0.0
      */
     handle(method, handler) {
         this.#overrides.set(method, handler);
     }
-    /** Restore the default behaviour of a method replaced with {@link TestHost.handle}. */
+    /**
+     * Restore the default behaviour of a method replaced with {@link TestHost.handle}.
+     *
+     * @capability None.
+     *
+     * @example Restore the default answer after a simulated failure
+     * The first write fails, the second succeeds. `reset` removes the handler
+     * that `handle` installed, so the method is answered by the test host
+     * again.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * host.handle("clipboard.writeText", () => {
+     *   throw new HostError("failed", "denied");
+     * });
+     * await assert.rejects(plugin.clipboard.writeText("x"));
+     * host.reset("clipboard.writeText");
+     * await plugin.clipboard.writeText("x"); // the default handler again
+     * ```
+     *
+     * @since 1.0.0
+     */
     reset(method) {
         this.#overrides.delete(method);
     }
@@ -1896,6 +2118,22 @@ export class TestHost {
      *
      * @param event - The wire event name.
      * @param data - The event payload (wire-level shape).
+     *
+     * @capability None.
+     *
+     * @example Deliver a raw event the helpers do not cover
+     * The test pushes a `window.state` event after changing `layout` by hand.
+     * Like the player, the host delivers it only when the plugin subscribed;
+     * most tests use `setSource`, `setMainWindow` and the other helpers
+     * instead.
+     * ```ts
+     * declare const host: TestHost;
+     * // ---cut---
+     * host.emit("window.state", {}); // no facts: the SDK reads window.state again
+     * await host.settle();
+     * ```
+     *
+     * @since 1.0.0
      */
     emit(event, data) {
         if ([
@@ -1935,6 +2173,9 @@ export class TestHost {
      * host.setSource({ phase: "ended", terminalReason: "natural" });
      * await host.settle();
      * ```
+     *
+     * @capability None.
+     * @since 1.0.0
      */
     setSource(patch) {
         this.source = {
@@ -1975,6 +2216,9 @@ export class TestHost {
      * assert.equal(plugin.window.state.fullscreen, true);
      * host.setMainWindow({ pictureInPicture: { supported: true, active: false } });
      * ```
+     *
+     * @capability None.
+     * @since 1.0.0
      */
     setMainWindow(patch) {
         const entering = patch.fullscreen !== undefined &&
@@ -1993,6 +2237,22 @@ export class TestHost {
      * The pointer reached the right edge in fullscreen (`true`) or left the
      * popped-out sidebar (`false`): the attached sidebar pops out or collapses
      * (reference §6.3). No effect outside fullscreen, when hidden or floating.
+     *
+     * @capability None.
+     *
+     * @example Pop the sidebar out in fullscreen
+     * The pointer reaches the right edge in fullscreen and the attached
+     * sidebar pops out over the video. Outside fullscreen, or with the
+     * sidebar hidden or floating, nothing happens.
+     * ```ts
+     * declare const host: TestHost;
+     * // ---cut---
+     * host.setMainWindow({ fullscreen: true });
+     * host.popSidebar(true);
+     * await host.settle();
+     * ```
+     *
+     * @since 1.0.0
      */
     popSidebar(popped) {
         const sidebar = this.layout.sidebar;
@@ -2036,6 +2296,9 @@ export class TestHost {
      * await host.settle();
      * assert.equal(plugin.player.isCurrent(before), false);
      * ```
+     *
+     * @capability None.
+     * @since 1.0.0
      */
     openElsewhere(source, phase = "ready") {
         this.#intent({ kind: "open", source, startPaused: false });
@@ -2063,6 +2326,9 @@ export class TestHost {
      * const [producer] = host.producers.values();
      * host.failStream(producer!.id, "producer transport closed");
      * ```
+     *
+     * @capability None.
+     * @since 1.5.7
      */
     failStream(producerId, message) {
         const producer = this.producers.get(producerId);
@@ -2081,11 +2347,12 @@ export class TestHost {
      * the conflict rule orders them. A disabled command lets the key pass to
      * the next command bound to it (SDK 1.5.12, as player 0.4.3): the one it
      * shadowed, then the global scope. The first enabled one runs; `press`
-     * resolves after it ran (`"ran"`), or rejects when it is busy. When only
-     * disabled commands hold the key, the first one with a `reason` shows the
-     * reason on the OSD and eats the key (`"reason"`, see `host.osd`);
-     * without a reason the key goes on to the focused control (`"passed"`,
-     * nothing runs). Rejects when nothing is bound. Bindings use the
+     * resolves after it ran (`"ran"`). When only disabled commands hold the
+     * key, the first of them decides, as in the player: with a `reason` it
+     * shows the reason on the OSD and eats the key (`"reason"`, see
+     * `host.osd`); without one the key goes on to the focused control
+     * (`"passed"`, nothing runs). Unlike the player, which only logs a key
+     * that reaches a busy command, `press` then rejects, so a test notices. Rejects when nothing is bound. Bindings use the
      * reference syntax (`"Space"`, `"Ctrl+O"`, `"Mouse:WheelUp"`), and user
      * overrides in `bindings.overlay` apply.
      *
@@ -2102,6 +2369,12 @@ export class TestHost {
      * await host.press("Ctrl+B"); // a global binding
      * await host.press("Delete", { panel: true }); // while the panel has focus
      * ```
+     *
+     * @capability None.
+     * @throws `command` (rejects) A `HostError`: the command that would run is
+     *   busy (the player only logs this).
+     * @throws `Error` (rejects) Nothing is bound to the key.
+     * @since 1.0.0
      */
     async press(binding, options = {}) {
         const claims = this.#claims();
@@ -2117,14 +2390,15 @@ export class TestHost {
             await command(enabled).run();
             return "ran";
         }
-        for (const id of ids) {
-            const reason = this.commands.has(id)
-                ? command(id).display.reason
-                : command(id).state.reason;
-            if (typeof reason === "string" && reason !== "") {
-                this.osd.push(reason);
-                return "reason";
-            }
+        // Like the player: only the first disabled command counts; without a
+        // reason the key goes on to the focused control.
+        const first = ids[0];
+        const reason = this.commands.has(first)
+            ? command(first).display.reason
+            : command(first).state.reason;
+        if (typeof reason === "string" && reason !== "") {
+            this.osd.push(reason);
+            return "reason";
         }
         return "passed";
     }
@@ -2232,6 +2506,9 @@ export class TestHost {
      * const rows = host.window("chat").props["messages"] as { body: Json }[];
      * assert.equal(host.markdown(rows[0]!.body)?.text, "**Hello**");
      * ```
+     *
+     * @capability None.
+     * @since 1.1.0
      */
     markdown(value) {
         const doc = value
@@ -2248,6 +2525,21 @@ export class TestHost {
     /**
      * Replace the plugin list and push `packages.changed` (another plugin
      * started, stopped, was installed or removed).
+     *
+     * @capability None.
+     *
+     * @example Simulate another plugin starting
+     * The plugin's store window hears that a plugin is running now. The list
+     * replaces `packages` and is pushed as `packages.changed`, which the
+     * plugin's `packages.onChange` listeners receive.
+     * ```ts
+     * declare const host: TestHost;
+     * // ---cut---
+     * host.setPackages([...host.packages]); // edit a copy, then push it
+     * await host.settle();
+     * ```
+     *
+     * @since 1.0.0
      */
     setPackages(list) {
         this.packages = list;
@@ -2297,6 +2589,25 @@ export class TestHost {
      * Simulate another plugin calling `player.next()` / `previous()`: the host
      * asks this plugin's sequence provider. Rejects with `unavailable` when
      * there is no provider or its flag is false.
+     *
+     * @capability None.
+     * @throws `unavailable` (rejects) A `HostError`: there is no sequence
+     *   provider, or its flag is false.
+     *
+     * @example Ask the plugin's provider for the next item
+     * Another plugin calls `player.next()`; the host asks the plugin under
+     * test, which is the sequence provider, and the test checks what it
+     * opened.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * await host.step("next");
+     * await host.settle();
+     * assert.equal(host.source.source, "/media/b.mp4");
+     * ```
+     *
+     * @since 1.0.0
      */
     step(direction) {
         return this.request("sequence.step", { direction });
@@ -2304,6 +2615,23 @@ export class TestHost {
     /**
      * The plugin's command with this local id. Throws when it is not
      * registered (never added, or disposed).
+     *
+     * @capability None.
+     *
+     * @example Read a command's state after a change
+     * The test checks that Export becomes enabled once a file is ready. The
+     * record is updated as the plugin sends new state; read it after
+     * `settle()`.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * host.setSource({ phase: "ready", duration: 60 });
+     * await host.settle();
+     * assert.equal(host.command("export").state.enabled, true); // throws if not registered
+     * ```
+     *
+     * @since 1.0.0
      */
     command(id) {
         const command = this.commands.get(id);
@@ -2384,6 +2712,9 @@ export class TestHost {
      * await host.settle();
      * assert.equal(host.window("picture").props["brightness"], 0);
      * ```
+     *
+     * @capability None.
+     * @since 1.0.0
      */
     window(id) {
         const window = this.windows.get(id);
@@ -2409,6 +2740,9 @@ export class TestHost {
      * panel.emit("select", 2);
      * await host.settle();
      * ```
+     *
+     * @capability None.
+     * @since 1.0.0
      */
     mounted() {
         if (!this.panel)
@@ -2428,6 +2762,9 @@ export class TestHost {
      * // ---cut---
      * assert.deepEqual(host.sent("osd.show").at(-1), { text: "Saved" });
      * ```
+     *
+     * @capability None.
+     * @since 1.0.0
      */
     sent(method) {
         return this.calls
@@ -2477,6 +2814,10 @@ export class TestHost {
      *   await host.settle(20);
      * assert.equal(window.props["status-text"], expected);
      * ```
+     *
+     * @capability None.
+     * @throws Never.
+     * @since 1.0.0
      */
     async settle(ms = 0) {
         const deadline = Date.now() + ms;
@@ -2489,6 +2830,23 @@ export class TestHost {
     /**
      * Close the fake stream servers and delete the host's temporary
      * directories. `stop()` from {@link startPlugin} calls it.
+     *
+     * @capability None.
+     *
+     * @example Clean up a host that was never started
+     * A test that made a host but failed before `startPlugin` removes the
+     * host's temporary directories itself. `stop()` from `startPlugin` calls
+     * `close` for you otherwise.
+     * ```ts
+     * const host = new TestHost();
+     * try {
+     *   // … preset the host; the test fails here …
+     * } finally {
+     *   host.close(); // deletes the host's temporary data
+     * }
+     * ```
+     *
+     * @since 1.0.0
      */
     close() {
         for (const producer of this.producers.values())
@@ -4138,6 +4496,16 @@ export class TestHost {
  *   }
  * });
  * ```
+ *
+ * @remarks
+ * The way into a plugin's tests: one call starts the plugin the way the
+ * player's runner does and returns the host to drive, the `plugin` object
+ * to call directly, and `stop` to end it like the player.
+ *
+ * @capability None.
+ * @see [Test a plugin](../../docs/how-to/testing.md)
+ * @since 1.0.0
+ * @category Testing
  */
 export async function startPlugin(activate, options = {}) {
     const host = options.host ?? new TestHost();