@forgebook/testing 0.1.8 → 0.2.0

package/README.md

@@ -107,12 +107,23 @@ import { storyTestViteConfig } from "@forgebook/testing/vite";
 export default storyTestViteConfig(import.meta.dirname, react());
 ```
 
+The config holds the framework's own Vite plugins (React's, or Solid's that compiles the stories' JSX), as the catalogue
+does: don't add them again.
+
 Then `npx playwright install chromium` once, and `playwright test -c test/stories/playwright.config.ts` starts the
 frame page and runs one test per story and variant (light, dark, both with more contrast, a narrow width, and the
 structure view), starting Vite through the package manager that runs them (`vite` in `testServer.ts` names
 another command). A story that breaks a rule fails all its variants; `storyBrowserTests` also takes `check`, a rule of
 the package's own run on every frame.
 
+A story about logic (`parameters: { logic: true }`, a hook's or a function's scene) is tested once, in the catalogue's
+default view, named `logic`: the variants only change how it looks. Its test still waits for the frame to be ready, so
+its play has to pass, and fails on an error in the page; axe runs too, since the scene is a page a person uses and a
+demo that fails WCAG is a bad example to copy. The checks about looks are left out: the spills and the overlays (layout
+at the variants' widths) and the package's own `check`, and a screenshot run takes no reference image of it.
+`forgebook check` runs the same checks on it, and with `--all-variants` both it and `forgebook shot` open it once, in
+the default view.
+
 ### On the server
 
 One test file and a Vitest configuration with the catalogue's plugin, which reads the source's
@@ -158,3 +169,25 @@ translation catalogue), its HTML checked.
 | `forgebook-shot` | Opens one story of a running catalogue and reports it with a picture |
 
 More: [Forgebook's README](https://github.com/ensiria/forgebook/blob/develop/packages/forgebook/README.md).
+
+## Writing a framework adapter
+
+A framework is an adapter package: a renderer, a code writer and a docs reader. `@forgebook/testing/conformance` is what
+every adapter passes, in its own Vitest with a simulated page, so a framework is done when this is green:
+
+```ts
+import { describeAdapter } from "@forgebook/testing/conformance";
+
+describeAdapter({ name: "Solid", renderer, drawing, decorator, codeOf, docsOf });
+```
+
+`drawing(name)` gives a story with a button showing `Hello <name> <clicks>`, its clicks in its own state, which throws
+for `THROWING_NAME`. `decorator(label)` draws a story inside a `section` with that `data-decorator`. A renderer's
+`renderToString` may return a promise. The frame takes only the drawing half, a `FrameRenderer` of `forgebook/renderer`:
+a framework's frame page imports a module without the server render, so the server renderer stays out of a static
+catalogue and of a first start's pre-bundle (`reactFrameRenderer` in `@forgebook/react`). A framework whose page and
+server builds differ runs the suite twice, with `half: "page"` in a simulated page and `half: "server"` in Node: Svelte
+compiles a component apart for each, and Solid's `solid-js/web` is its browser build or its server build, never both.
+`test/conformance.test.tsx` in `@forgebook/react` and `@forgebook/preact`, `test/conformance.test.ts` in
+`@forgebook/vue`, `@forgebook/web-components`, `@forgebook/html` and `@forgebook/angular`, and the two `conformance`
+tests of `@forgebook/svelte` and of `@forgebook/solid` are complete examples.

package/dist/bin/forgebook-heights/forgebook-heights.d.mts

@@ -1,3 +1,2 @@
 #!/usr/bin/env node
 export {};
-//# sourceMappingURL=forgebook-heights.d.mts.map

package/dist/bin/forgebook-heights/forgebook-heights.mjs

@@ -121,4 +121,3 @@ await defineScript({
         }
     }
 }).run();
-//# sourceMappingURL=forgebook-heights.mjs.map

package/dist/bin/forgebook-heights/measureHeights.d.ts

@@ -81,4 +81,3 @@ export type MeasureResult = {
  */
 export declare const measureStories: (request: MeasureRequest) => Promise<MeasureResult>;
 export {};
-//# sourceMappingURL=measureHeights.d.ts.map

package/dist/bin/forgebook-heights/measureHeights.js

@@ -12,6 +12,7 @@
  * @module
  */
 import { chromium } from "@playwright/test";
+import { codeLiteral } from "forgebook/code-literal";
 import { STATUS_ATTRIBUTE } from "forgebook/frame-status";
 import { STORY_IDS_ELEMENT } from "forgebook/story-ids-element";
 import { frameAddressOf } from "forgebook/view-state";
@@ -115,7 +116,7 @@ const measureStory = async (page, address, storyId, widths, timeout) => {
     await page.setViewportSize({ width: first, height: VIEWPORT_HEIGHT });
     await page.goto(new URL(frameAddressOf("frame.html", storyId, ""), address).href);
     const status = await page
-        .waitForFunction(`document.documentElement.getAttribute(${JSON.stringify(STATUS_ATTRIBUTE)})`, undefined, {
+        .waitForFunction(`document.documentElement.getAttribute(${codeLiteral(STATUS_ATTRIBUTE)})`, undefined, {
         timeout
     })
         .then(async (handle) => String(await handle.jsonValue()))
@@ -177,4 +178,3 @@ export const measureStories = async (request) => {
         await browser.close();
     }
 };
-//# sourceMappingURL=measureHeights.js.map

package/dist/bin/forgebook-heights/measureHeights.types.d.ts

@@ -24,4 +24,3 @@ export type HeightsReport = {
     /** The ones that failed, left out of the file. */
     readonly failures: readonly HeightFailure[];
 };
-//# sourceMappingURL=measureHeights.types.d.ts.map

package/dist/bin/forgebook-heights/measureHeights.types.js

@@ -4,4 +4,3 @@
  *
  * @module
  */
-//# sourceMappingURL=measureHeights.types.js.map

package/dist/bin/forgebook-shot/forgebook-shot.d.mts

@@ -1,3 +1,2 @@
 #!/usr/bin/env node
 export {};
-//# sourceMappingURL=forgebook-shot.d.mts.map

package/dist/bin/forgebook-shot/forgebook-shot.mjs

@@ -107,4 +107,3 @@ await defineScript({
         return shot;
     }
 }).run();
-//# sourceMappingURL=forgebook-shot.mjs.map

package/dist/bin/forgebook-shot/storyShot.d.ts

@@ -31,4 +31,3 @@ export declare const shotAddress: (catalogue: string, story: string, view: strin
  * @returns the report; a frame that never answers is `timeout`, not an exception.
  */
 export declare const takeShot: (request: ShotRequest) => Promise<StoryShot>;
-//# sourceMappingURL=storyShot.d.ts.map

package/dist/bin/forgebook-shot/storyShot.js

@@ -11,6 +11,7 @@
 import { AxeBuilder } from "@axe-core/playwright";
 import { chromium } from "@playwright/test";
 import { DEFAULT_A11Y_TAGS } from "forgebook/catalogue";
+import { codeLiteral } from "forgebook/code-literal";
 import { STATUS_ATTRIBUTE } from "forgebook/frame-status";
 import { frameAddressOf } from "forgebook/view-state";
 /**
@@ -44,7 +45,7 @@ export const takeShot = async (request) => {
         await page.goto(address);
         // a text expression: the command runs on Node, where the page's own globals are not typed
         const status = await page
-            .waitForFunction(`document.documentElement.getAttribute(${JSON.stringify(STATUS_ATTRIBUTE)})`, undefined, {
+            .waitForFunction(`document.documentElement.getAttribute(${codeLiteral(STATUS_ATTRIBUTE)})`, undefined, {
             timeout: request.timeout
         })
             .then(async (handle) => ((await handle.jsonValue()) === "ready" ? "ready" : "error"))
@@ -80,4 +81,3 @@ export const takeShot = async (request) => {
         await browser.close();
     }
 };
-//# sourceMappingURL=storyShot.js.map

package/dist/bin/forgebook-shot/storyShot.types.d.ts

@@ -29,4 +29,3 @@ export type StoryShot = {
     /** The accessibility rules the story breaks, when asked (`--a11y`). */
     readonly violations?: readonly Violation[];
 };
-//# sourceMappingURL=storyShot.types.d.ts.map

package/dist/bin/forgebook-shot/storyShot.types.js

@@ -1 +0,0 @@
-//# sourceMappingURL=storyShot.types.js.map

package/dist/src/browserTests.d.ts

@@ -1,19 +1,3 @@
-/**
- * One Playwright test per story and variant, on the catalogue's frame pages: the address the catalogue shows is the
- * address the tests open.
- *
- * @remarks
- * Each test opens the frame for a story in a variant (the theme, the contrast, the style sheets), waits for the
- * frame to say the story is shown (`data-forgebook-status`), its story clock held at its start, and fails on an error in the console or the page, or on
- * an axe violation of WCAG 2.2 A and AA, on an element that spills out of its parent (`forgebook/spills`: what overlaps a
- * neighbour when the story is narrower than it was drawn for), on an overlay its play leaves open past the frame the
- * catalogue would give it (`overlays.ts`: the story then declares `parameters.height`), or on the source's own
- * `check`. The variants include a
- * narrow frame, as wide as the catalogue's stage beside the props panel. With `screenshot` it compares the frame with its reference image instead,
- * for the visual tests, which run in the Playwright container so fonts and rendering are the same everywhere.
- *
- * @module
- */
 import { type Page } from "@playwright/test";
 import { type CatalogueLists } from "forgebook/catalogue";
 import { type ViewSwitch } from "forgebook/switches";
@@ -68,4 +52,3 @@ export type StoryBrowserTestsOptions = StoryFilesOptions & {
  * the source's own.
  */
 export declare const storyBrowserTests: (options: StoryBrowserTestsOptions) => void;
-//# sourceMappingURL=browserTests.d.ts.map

package/dist/src/browserTests.js

@@ -11,19 +11,23 @@
  * `check`. The variants include a
  * narrow frame, as wide as the catalogue's stage beside the props panel. With `screenshot` it compares the frame with its reference image instead,
  * for the visual tests, which run in the Playwright container so fonts and rendering are the same everywhere.
+ * A story about logic (`parameters.logic`) is tested once, in the default view, without the layout checks, and never
+ * pictured (`storyTestPlan.ts`).
  *
  * @module
  */
+import { existsSync } from "node:fs";
 import { expect, test } from "@playwright/test";
 import { catalogueSettings } from "forgebook/catalogue";
 import { STATUS_ATTRIBUTE } from "forgebook/frame-status";
 import { heldClockAddress } from "forgebook/story-clock";
-import { storyTree, testedStoryLocations } from "forgebook/story-tree";
+import { formerStoryId, storyTree, testedStoryLocations } from "forgebook/story-tree";
 import { DEFAULT_SWITCHES, switchWithRole } from "forgebook/switches";
 import { defaultView, frameAddress } from "forgebook/view-state";
 import { isOverlayChecked } from "./overlays.js";
 import { axeProblems, overlayProblems, spillProblems, watchedErrors } from "./storyCheck.js";
 import { indexedSource } from "./storyFiles.js";
+import { plannedStoryTests } from "./storyTestPlan.js";
 /** The narrow variant's width: about the catalogue's stage beside the props panel in a laptop window, in CSS px. */
 export const NARROW_WIDTH = 560;
 /**
@@ -58,6 +62,41 @@ export const storyVariants = (switches) => {
 };
 /** The variants of a catalogue with the default switches: light, dark, both at more contrast, structure, narrow. */
 export const STORY_VARIANTS = storyVariants(DEFAULT_SWITCHES);
+/** A problem list's messages, so a failing test names each problem. */
+const messages = (problems) => problems.map((problem) => problem.message);
+/**
+ * Runs the checks of one planned test on a shown story: axe, then for a story about its looks the spills, the
+ * source's own check, and the overlays last (it resizes the window, which may close what the story left open). A story
+ * about logic gets axe only.
+ *
+ * @param page - the story's frame, ready.
+ * @param planned - the story, its variant and whether its layout is checked.
+ * @param a11y - the catalogue's accessibility rules.
+ * @param check - the source's own check, if any.
+ */
+const expectChecksPass = async (page, planned, a11y, check) => {
+    expect(messages(await axeProblems(page, a11y))).toEqual([]);
+    if (!planned.hasLookChecks)
+        return;
+    expect(messages(await spillProblems(page))).toEqual([]);
+    await check?.(page);
+    expect(messages(await overlayProblems(page, isOverlayChecked(planned.variant.view), planned.story.height))).toEqual([]);
+};
+/**
+ * A story's screenshot name in a variant: by its id, or by the id an earlier rule gave it while only a screenshot of
+ * that name is stored, so the screenshots taken before the ids followed Storybook's keep comparing.
+ *
+ * @param id - the story's id.
+ * @param formerId - the id the former rule gave it.
+ * @param variant - the variant's name.
+ */
+const screenshotName = (id, formerId, variant) => {
+    const named = (storyId) => `${storyId.replace(":", "--")}--${variant}.png`;
+    const isStored = (name) => existsSync(test.info().snapshotPath(name, { kind: "screenshot" }));
+    return named(formerId) !== named(id) && !isStored(named(id)) && isStored(named(formerId))
+        ? named(formerId)
+        : named(id);
+};
 /**
  * Declares the tests, one `describe` per component and one test per story and variant.
  *
@@ -69,44 +108,42 @@ export const storyBrowserTests = (options) => {
     const variants = options.variants ?? storyVariants(switches);
     const catalogue = catalogueSettings("", switches, options.lists);
     const defaults = defaultView(catalogue);
-    const tree = storyTree([indexedSource(options)]);
+    const source = indexedSource(options);
+    const tree = storyTree([source]);
     const groups = Map.groupBy(testedStoryLocations(tree), (location) => location.component.title);
     for (const [title, locations] of groups) {
+        const planned = plannedStoryTests(locations.map((location) => location.story), variants, screenshot);
+        // a component whose stories are all about logic has nothing to picture
+        if (planned.length === 0)
+            continue;
         test.describe(title, () => {
-            for (const { story } of locations) {
-                for (const variant of variants) {
-                    test(`${story.name} · ${variant.name}`, async ({ page }) => {
-                        const errors = watchedErrors(page);
-                        if (variant.width !== undefined)
-                            await page.setViewportSize({ width: variant.width, height: 800 });
-                        // a Live story is checked and pictured at its start: its clock held, so its image never changes;
-                        // always on its page's own colour, whatever a variant names: a backdrop is for looking
-                        const view = {
-                            ...defaults,
-                            ...variant.view,
-                            switches: { ...defaults.switches, ...variant.view.switches },
-                            backdrop: "plain"
-                        };
-                        await page.goto(heldClockAddress(frameAddress(frameUrl, story.id, view, switches)));
-                        await expect(page.locator("html")).toHaveAttribute(STATUS_ATTRIBUTE, "ready");
-                        if (screenshot) {
-                            await expect(page).toHaveScreenshot(`${story.id.replace(":", "--")}--${variant.name}.png`, {
-                                fullPage: true,
-                                animations: "disabled"
-                            });
-                            return;
-                        }
-                        const messages = (problems) => problems.map((problem) => problem.message);
-                        expect(messages(await axeProblems(page, catalogue.a11y))).toEqual([]);
-                        expect(messages(await spillProblems(page))).toEqual([]);
-                        await check?.(page);
-                        // last: it resizes the window, which may close what the story left open
-                        expect(messages(await overlayProblems(page, isOverlayChecked(variant.view), story.height))).toEqual([]);
-                        expect(errors).toEqual([]);
-                    });
-                }
+            for (const { story, variant, hasLookChecks } of planned) {
+                test(`${story.name} · ${variant.name}`, async ({ page }) => {
+                    const errors = watchedErrors(page);
+                    if (variant.width !== undefined)
+                        await page.setViewportSize({ width: variant.width, height: 800 });
+                    // a Live story is checked and pictured at its start: its clock held, so its image never changes;
+                    // always on its page's own colour, whatever a variant names: a backdrop is for looking
+                    const view = {
+                        ...defaults,
+                        ...variant.view,
+                        switches: { ...defaults.switches, ...variant.view.switches },
+                        backdrop: "plain"
+                    };
+                    await page.goto(heldClockAddress(frameAddress(frameUrl, story.id, view, switches)));
+                    await expect(page.locator("html")).toHaveAttribute(STATUS_ATTRIBUTE, "ready");
+                    if (screenshot) {
+                        const name = screenshotName(story.id, formerStoryId(source.id, title, story.exportName), variant.name);
+                        await expect(page).toHaveScreenshot(name, {
+                            fullPage: true,
+                            animations: "disabled"
+                        });
+                        return;
+                    }
+                    await expectChecksPass(page, { story, variant, hasLookChecks }, catalogue.a11y, check);
+                    expect(errors).toEqual([]);
+                });
             }
         });
     }
 };
-//# sourceMappingURL=browserTests.js.map

package/dist/src/checkPage.d.ts

@@ -0,0 +1,16 @@
+import { type CatalogueLists } from "forgebook/catalogue";
+import type { StoryCheckReport } from "forgebook/story-check";
+/** What a page check is asked. */
+export type PageCheckRequest = {
+    /** The pages' addresses. */
+    readonly addresses: readonly string[];
+    /** The catalogue's lists: its accessibility rules. */
+    readonly lists: CatalogueLists;
+};
+/**
+ * Checks pages, on one browser.
+ *
+ * @param request - the addresses and the catalogue's settings.
+ * @returns one result per page, in the request's order.
+ */
+export declare const checkPages: ({ addresses, lists }: PageCheckRequest) => Promise<StoryCheckReport>;

package/dist/src/checkPage.js

@@ -0,0 +1,68 @@
+/**
+ * A real page of an application checked as a story is: accessibility, what spills, and its errors.
+ *
+ * @remarks
+ * An agent verifies the screen it built, not only the stories behind it, so `forgebook check-page` opens any address.
+ * Loaded from the project only when it runs, like `checkStories.ts`. No frame says this page is ready, so it counts as
+ * ready when the network goes quiet, or after `QUIET_MS` for a page that keeps a connection open, which is checked as it
+ * stands then. The report has a story check's shape, the address standing for the story's id.
+ *
+ * @module
+ */
+import { chromium } from "@playwright/test";
+import { catalogueSettings } from "forgebook/catalogue";
+import { axeProblems, errorProblems, focusProblems, spillProblems, watchedErrors } from "./storyCheck.js";
+/** How long a page gets for its network to go quiet, in milliseconds. */
+const QUIET_MS = 10_000;
+/** One page, checked. */
+const checkedPage = async (address, open, a11y) => {
+    const page = await open();
+    const errors = watchedErrors(page);
+    const result = (problems) => ({
+        storyId: address,
+        view: "",
+        frame: address,
+        problems
+    });
+    try {
+        const response = await page.goto(address);
+        await page.waitForLoadState("networkidle", { timeout: QUIET_MS }).catch(() => undefined);
+        if (response !== null && !response.ok()) {
+            return result([{ kind: "frame", message: `It answered ${response.status()}` }]);
+        }
+        return result([
+            ...(await axeProblems(page, a11y)),
+            ...(await spillProblems(page, "body")),
+            ...(await focusProblems(page)),
+            ...errorProblems(errors)
+        ]);
+    }
+    catch (error) {
+        return result([{ kind: "frame", message: error instanceof Error ? error.message : String(error) }]);
+    }
+    finally {
+        await page.close();
+    }
+};
+/**
+ * Checks pages, on one browser.
+ *
+ * @param request - the addresses and the catalogue's settings.
+ * @returns one result per page, in the request's order.
+ */
+export const checkPages = async ({ addresses, lists }) => {
+    const { a11y } = catalogueSettings("", [], lists);
+    const browser = await chromium.launch();
+    try {
+        // from a context of its own: axe opens pages of its own, which a bare `browser.newPage()` cannot share
+        const context = await browser.newContext();
+        const results = [];
+        for (const address of addresses) {
+            results.push(await checkedPage(address, () => context.newPage(), a11y));
+        }
+        return { schema: 1, results };
+    }
+    finally {
+        await browser.close();
+    }
+};

package/dist/src/checkStories.d.ts

@@ -6,4 +6,3 @@ import type { StoryCheckReport, StoryCheckRequest } from "forgebook/story-check"
  * @returns one result per story and view, in the request's order.
  */
 export declare const checkStories: (request: StoryCheckRequest) => Promise<StoryCheckReport>;
-//# sourceMappingURL=checkStories.d.ts.map

package/dist/src/checkStories.js

@@ -1,7 +1,9 @@
 import { catalogueSettings } from "forgebook/catalogue";
 import { isOverlayChecked } from "./overlays.js";
-import { axeProblems, errorProblems, overlayProblems, spillProblems, watchedErrors } from "./storyCheck.js";
+import { askModel, storySight } from "./semanticJudge.js";
+import { axeProblems, errorProblems, focusProblems, overlayProblems, spillProblems, watchedErrors } from "./storyCheck.js";
 import { eachStoryPage, openedStory, READY_MS } from "./storyPages.js";
+import { hasLookChecks } from "./storyTestPlan.js";
 /**
  * One story in one view, checked.
  *
@@ -9,7 +11,7 @@ import { eachStoryPage, openedStory, READY_MS } from "./storyPages.js";
  * @param storyPage - the story and the view.
  * @param a11y - the catalogue's accessibility settings.
  */
-const checkedPage = async (page, storyPage, a11y) => {
+const checkedPage = async (page, storyPage, a11y, semantic) => {
     const errors = watchedErrors(page);
     const status = await openedStory(page, storyPage);
     const result = (problems) => ({
@@ -25,13 +27,19 @@ const checkedPage = async (page, storyPage, a11y) => {
         ]);
     if (status === "error")
         return result([{ kind: "frame", message: "The story could not be shown" }, ...errorProblems(errors)]);
-    return result([
-        ...(await axeProblems(page, a11y)),
-        ...(await spillProblems(page)),
-        // last of the page's checks: it resizes the window, which may close what the story left open
-        ...(await overlayProblems(page, isOverlayChecked(storyPage.view), storyPage.story.height)),
-        ...errorProblems(errors)
-    ]);
+    // a story about logic gets the suite's checks of a scene, not those about looks (`storyTestPlan.ts`)
+    const lookProblems = hasLookChecks(storyPage.story)
+        ? [
+            ...(await spillProblems(page)),
+            // last of the page's checks: it resizes the window, which may close what the story left open
+            ...(await overlayProblems(page, isOverlayChecked(storyPage.view), storyPage.story.height))
+        ]
+        : [];
+    const axe = await axeProblems(page, a11y);
+    const checked = result([...axe, ...lookProblems, ...(await focusProblems(page)), ...errorProblems(errors)]);
+    return semantic === undefined
+        ? checked
+        : { ...checked, judgements: await askModel(semantic, await storySight(page)) };
 };
 /**
  * Checks the stories a request names, in its views, on one browser.
@@ -41,7 +49,6 @@ const checkedPage = async (page, storyPage, a11y) => {
  */
 export const checkStories = async (request) => {
     const { a11y } = catalogueSettings("", request.switches, request.lists);
-    const results = await eachStoryPage(request, (page, storyPage) => checkedPage(page, storyPage, a11y));
+    const results = await eachStoryPage(request, (page, storyPage) => checkedPage(page, storyPage, a11y, request.semantic));
     return { schema: 1, results };
 };
-//# sourceMappingURL=checkStories.js.map

package/dist/src/conformance.d.ts

@@ -0,0 +1,46 @@
+import type { StoryCodeWriter, StoryDrawing, StoryRenderer } from "forgebook/renderer";
+import type { LoadedDecorator } from "forgebook/story-module";
+/** A half of the suite: what a story does in a page, or on a server. */
+export type AdapterHalf = "page" | "server";
+/** The name a subject's story throws for. */
+export declare const THROWING_NAME = "boom";
+/** What an adapter hands the suite. */
+export type AdapterSubject = {
+    /** The framework's name, in the tests' titles. */
+    readonly name: string;
+    /** Its renderer. */
+    readonly renderer: StoryRenderer;
+    /**
+     * A drawing of a story with a button that shows `Hello <name> <clicks>`, counting its clicks in its own state, and that
+     * throws while drawn when the name is `THROWING_NAME`.
+     *
+     * @param name - the name, as the story's args carry it.
+     */
+    readonly drawing: (name: string) => StoryDrawing;
+    /**
+     * A decorator that draws the story inside a `section` with this `data-decorator` value, written as the framework
+     * writes one.
+     *
+     * @param label - the value.
+     */
+    readonly decorator: (label: string) => LoadedDecorator;
+    /** The code writer the shell uses. */
+    readonly codeOf: StoryCodeWriter;
+    /**
+     * The framework's docs of a story file's component, as `extractStoryComponent` reads them. None skips the check, for an
+     * adapter with no documented types yet.
+     */
+    readonly docsOf?: () => unknown;
+    /**
+     * The half of the suite this run checks, for a framework whose components are compiled apart for a page and for a
+     * server: its package runs the suite once in a simulated page (`page`, with the code writer and the docs) and once in
+     * Node (`server`). Both halves when none.
+     */
+    readonly half?: AdapterHalf;
+};
+/**
+ * The suite of an adapter.
+ *
+ * @param subject - the adapter's subject.
+ */
+export declare const describeAdapter: (subject: AdapterSubject) => void;