@executablemd/testing 0.3.1

package/types/src/test-api.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Test Api — contextual operations for testing mode (specs/testing-spec.md).
+ *
+ * `testing` is the activation switch: false by default, true beneath
+ * `<Testing>` (or root activation via a `useTesting()` session).
+ * Both perform the identical `Test.around({ testing: () => true })` install,
+ * which is what makes `xmd test` equivalent to wrapping the entrypoint in
+ * `<Testing>`.
+ *
+ * `record` delegates outward through nested collectors, so every enclosing
+ * `<Testing>` boundary and the run-level collector observe each completed
+ * test. `boundary` reports each `<Testing>` element's aggregate outcome.
+ */
+import type { Operation } from "effection";
+/** A completed test, in discovery order. Never holds rendered markdown. */
+export interface TestResult {
+    status: "pass" | "fail";
+    name?: string;
+    /** "path:line:column" ("line:column" for dynamically scanned sources). */
+    location: string;
+    error?: {
+        kind: "assertion" | "timeout" | "teardown" | "error";
+        message: string;
+        actual?: string;
+        expected?: string;
+    };
+}
+/** Aggregate outcome of one `<Testing>` boundary. */
+export interface BoundaryOutcome {
+    tests: number;
+    failed: number;
+}
+export interface TestApi {
+    /** Whether testing mode is active in the current scope. */
+    testing: boolean;
+    /** Whether expansion is currently inside a `<Test>` body. */
+    inTest: boolean;
+    /** Whether assertion diagnostics render during regular execution. */
+    verbose: boolean;
+    /** Whether a useTesting() session is already active in this scope. */
+    sessionActive: boolean;
+    /** Record a completed test. Collectors delegate outward via `next`. */
+    record(result: TestResult): Operation<void>;
+    /** Completed tests recorded by the nearest collector, discovery order. */
+    results(): Operation<TestResult[]>;
+    /** Report a `<Testing>` boundary's aggregate outcome. */
+    boundary(outcome: BoundaryOutcome): Operation<void>;
+}
+export declare const Test: import("@effectionx/context-api").Api<TestApi>;
+export declare const testing: Operation<boolean>, inTest: Operation<boolean>, verbose: Operation<boolean>, sessionActive: Operation<boolean>, record: (result: TestResult) => Operation<void>, results: () => Operation<TestResult[]>, boundary: (outcome: BoundaryOutcome) => Operation<void>;
+/** A document execution failed its testing outcome (test failures or zero tests). */
+export declare class TestFailureError extends Error {
+    name: string;
+}

package/types/src/use-testing.d.ts

@@ -0,0 +1,25 @@
+/**
+ * useTesting — scope-local testing composition (specs/testing-spec.md).
+ *
+ * One `useTesting()` session per execution scope: it installs the testing
+ * vocabulary, the collection and completion-policy middleware, and root
+ * activation, then returns a session handle whose `results` operation
+ * snapshots completed tests in discovery order. Every install is removed
+ * with the session's Effection scope.
+ *
+ * ```ts
+ * const tests = yield* useTesting();
+ * const execution = yield* execute(options);
+ * const outcome = yield* execution;          // Result<string>
+ * const results = yield* tests.results;
+ * ```
+ */
+import type { Operation } from "effection";
+import type { TestResult } from "./test-api.js";
+export interface Testing {
+    /** Immutable snapshot of completed tests, in discovery order. */
+    readonly results: Operation<readonly TestResult[]>;
+}
+export declare function useTesting(options?: {
+    verbose?: boolean;
+}): Operation<Testing>;

package/types/src/vocabulary.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Vocabulary registration (specs/testing-spec.md).
+ *
+ * Teaches the expansion loop the testing words — `<Testing>`, `<Test>`, and
+ * the assertion components — via the core `expandInvocation` hook, and
+ * decorates the core Execution Api so explicit `<Testing>` boundaries affect
+ * the execution outcome even when root testing is inactive.
+ *
+ * Registration is distinct from activation: installing the vocabulary
+ * leaves `testing` false, so `<Test>` skips and assertions stay usable.
+ * Root activation is `useTesting()`'s job.
+ *
+ * Installs are scope-local — call this inside a bounded scope (one CLI
+ * command invocation, one `scoped()` block).
+ */
+import type { Operation } from "effection";
+import type { DocumentExecution } from "@executablemd/core";
+import type { TestHandlers } from "./handlers.js";
+export declare function installTestingVocabulary(options?: {
+    verbose?: boolean;
+}): Operation<void>;
+/**
+ * Install a specific handler set. Internal seam: tests inject handlers built
+ * with a short timeout; the public path always uses the fixed 20 seconds.
+ */
+export declare function installHandlers(handlers: TestHandlers, options?: {
+    verbose?: boolean;
+}): Operation<void>;
+/**
+ * Map an execution's completion: an `Ok` becomes `Err(failure())` when the
+ * policy reports one, after the inner completion — and therefore its closed
+ * output stream — settles. An existing `Err` passes through unchanged.
+ */
+export declare function decorateCompletion(inner: DocumentExecution, failure: () => Error | undefined): DocumentExecution;