@matter/testing 0.17.9 → 0.18.0-alpha.0-20260812-4d7f2790e

package/dist/esm/chip/cert/cert-context.d.ts

@@ -0,0 +1,115 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Subject } from "../../device/subject.js";
+import type { ControllerAdapter } from "./controller-adapter.js";
+import type { LogFollower } from "./log-follower.js";
+/**
+ * Access to a single device's log stream.
+ */
+export interface LogSource {
+    follow(): AsyncIterable<string>;
+}
+/**
+ * Kind of implementation backing a {@link CertDevice}.
+ */
+export type DeviceFlavor = "chip-docker" | "chip-local" | "matterjs";
+/**
+ * How a {@link CertDevice}'s backing process or container ended.
+ */
+export interface DeviceExitInfo {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+}
+/**
+ * A device participating in a cert test — a {@link Subject} plus the identity a step needs to
+ * distinguish backing implementations and detect a process/container crash.
+ */
+export interface CertDevice extends Subject {
+    readonly log: LogFollower;
+    readonly flavor: DeviceFlavor;
+    readonly exit: Promise<DeviceExitInfo>;
+}
+/**
+ * A {@link Subject.Factory} that's known to produce {@link CertDevice}s, not just plain
+ * {@link Subject}s. Lets cert-test wiring consume a factory's result without narrowing at every call
+ * site (see {@link ChipLocalSubject}/{@link ChipDockerSubject}/`registerMatterJsCertSubject`, all of
+ * which only ever construct {@link CertDevice}-conforming instances).
+ */
+export interface CertDeviceFactory extends Subject.Factory {
+    (domain: string, options?: Subject.Options): CertDevice;
+}
+/**
+ * Outcome of a single cert-test step.
+ */
+export type StepVerdict = "pass" | "fail" | "skipped" | "aborted";
+/**
+ * A single piece of evidence a step recorded while running.
+ */
+export interface CheckRecord {
+    type: "response" | "device-log" | "network";
+    verdict: "pass" | "fail" | "unverified";
+    detail?: string;
+    pattern?: string;
+    matched?: string;
+    logLine?: number;
+}
+/**
+ * Evidence hooks a {@link CertTest} step engine reports to. See {@link EvidenceRecorder} for the
+ * implementation that persists this to disk.
+ */
+export interface StepRecorder {
+    beginStep(step: CertStepDefinition): void;
+    /**
+     * Records evidence only; a failed check does not itself change the step's {@link StepVerdict}.
+     * A step signals failure by having its `run` throw, not by calling `check` with a failing verdict.
+     */
+    check(record: CheckRecord): void;
+    /** Returns the checks recorded for `step` (empty if it never began), for the caller's own end-of-step reporting. */
+    endStep(step: CertStepDefinition, verdict: StepVerdict, skipReason?: string): CheckRecord[];
+    /**
+     * Records that a device exited unexpectedly while the run was in progress. {@link CertTest}
+     * calls this and then fails the run itself; a recorder need only persist the information (see
+     * {@link EvidenceRecorder.deviceExited}).
+     */
+    deviceExited?(info: DeviceExitInfo): void;
+    /**
+     * Persists whatever evidence was recorded. Returns an implementation-defined locator for it
+     * (e.g. {@link EvidenceRecorder} returns the directory it wrote to); a recorder with nothing to
+     * persist returns an empty string.
+     */
+    flush(): Promise<string>;
+}
+/**
+ * Context passed to a {@link CertStepDefinition.run} implementation.
+ */
+export interface CertStepContext {
+    controllers: Record<string, ControllerAdapter>;
+    devices: Record<string, CertDevice>;
+    recorder: StepRecorder;
+}
+/**
+ * A single step of a cert test plan.
+ */
+export interface CertStepDefinition {
+    number: number | string;
+    text: string;
+    expected?: string;
+    pics?: string;
+    /** Device flavors this step supports; absent runs on every flavor (see `cert-dsl.ts`'s `certTest`/`.step`). */
+    flavors?: DeviceFlavor[];
+    run: (cx: CertStepContext) => Promise<void>;
+}
+/**
+ * A cert test plan translated to executable steps.
+ */
+export interface CertTestDefinition {
+    tc: string;
+    plan: string;
+    pics: string[];
+    app: string;
+    steps: CertStepDefinition[];
+}
+//# sourceMappingURL=cert-context.d.ts.map

package/dist/esm/chip/cert/cert-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cert-context.d.ts","sourceRoot":"","sources":["../../../../src/chip/cert/cert-context.ts"],"names":[],"mappings":"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"}

package/dist/esm/chip/cert/cert-context.js

@@ -0,0 +1,6 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+//# sourceMappingURL=cert-context.js.map

package/dist/esm/chip/cert/cert-context.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/chip/cert/cert-context.ts"],
+  "mappings": "AAAA;AAAA;AAAA;AAAA;AAAA;",
+  "names": []
+}

package/dist/esm/chip/cert/cert-dsl.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { CertStepContext, DeviceFlavor } from "./cert-context.js";
+export interface CertTestOptions {
+    plan: string;
+    pics: string[];
+    app: string;
+    /** Role name → "dut" (device under test) or "helper" (auxiliary controller). Default: `{ dut: "dut" }`. */
+    controllers?: Record<string, "dut" | "helper">;
+    /** Role name → app name. Default: `{ th: options.app }`. */
+    devices?: Record<string, string>;
+}
+export interface CertStepOptions {
+    pics?: string;
+    expected?: string;
+    /**
+     * Restricts this step to the listed device flavors — the minimal declaration mechanism for a TC
+     * whose TH app lacks a cluster/command on some flavors (see `TC-ACT-3.2.test.ts`'s AGENTS.md
+     * entry). Absent runs the step on every flavor, matching prior behavior.
+     */
+    flavors?: DeviceFlavor[];
+}
+export interface CertTestBuilder {
+    step(number: number | string, text: string, run: (cx: CertStepContext) => Promise<void>, opts?: CertStepOptions): CertTestBuilder;
+}
+/**
+ * Thrown by {@link certTest} when `options.devices` declares more than one device. Every device
+ * flavor (`ChipDockerSubject`/`ChipLocalSubject`/the matterjs registry) currently starts every
+ * device with the same hardcoded discriminator (3840), passcode (20202021), and operational port
+ * — fine for one device per run, but two devices in the same run would advertise identical mDNS
+ * commissionable records and (for chip flavors) contend for the same UDP port. Multi-device cert
+ * tests need per-role discriminator/passcode/port assignment before this can work; until then this
+ * throws instead of silently producing a flaky, ambiguous run.
+ */
+export declare class MultiDeviceUnsupportedError extends Error {
+    constructor(tc: string, roles: string[]);
+}
+/**
+ * Declares a cert test. Registers a mocha `it()` for `tc` immediately (mirroring
+ * `chip.ts`'s `defineTest`); the returned builder's `.step()` calls append to the step list that
+ * `it()`'s test body reads once mocha actually runs it, so step declarations may continue after
+ * this call returns.
+ */
+export declare function certTest(tc: string, options: CertTestOptions): CertTestBuilder;
+//# sourceMappingURL=cert-dsl.d.ts.map

package/dist/esm/chip/cert/cert-dsl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cert-dsl.d.ts","sourceRoot":"","sources":["../../../../src/chip/cert/cert-dsl.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAgBH,OAAO,EAGH,eAAe,EAGf,YAAY,EACf,MAAM,mBAAmB,CAAC;AAS3B,MAAM,WAAW,eAAe;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,2GAA2G;IAC3G,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,GAAG,QAAQ,CAAC,CAAC;IAC/C,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,eAAe;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,eAAe;IAC5B,IAAI,CACA,MAAM,EAAE,MAAM,GAAG,MAAM,EACvB,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,CAAC,EAAE,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,EAC3C,IAAI,CAAC,EAAE,eAAe,GACvB,eAAe,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;IAClD,YAAY,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,EAQtC;CACJ;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,eAAe,CAoD9E"}

package/dist/esm/chip/cert/cert-dsl.js

@@ -0,0 +1,288 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { env } from "node:process";
+import { promisify } from "node:util";
+import { Docker } from "../../docker/docker.js";
+import { Image } from "../../docker/image.js";
+import { afterOne, beforeOne } from "../../mocha.js";
+import { chip } from "../chip.js";
+import { State } from "../state.js";
+import { chipImageBase, ChipDockerSubject, ChipLocalSubject, resolveChipLocalAppDir } from "./chip-app-subject.js";
+import { CertTest, registerCertTestFactory } from "./cert-test.js";
+import { createControllerAdapter } from "./controller-adapter.js";
+import { resolveDeviceFlavor } from "./device-config.js";
+import { EvidenceRecorder } from "./evidence.js";
+import { matterJsCertSubjectFor } from "./matterjs-subject-registry.js";
+const execFileAsync = promisify(execFile);
+class MultiDeviceUnsupportedError extends Error {
+  constructor(tc, roles) {
+    super(
+      `certTest "${tc}" declares ${roles.length} devices (${roles.join(", ")}) via options.devices; every device flavor hardcodes discriminator 3840/passcode 20202021 (and, for chip flavors, a fixed operational port), so more than one device in a single run collides on mDNS advertisement and likely UDP port contention. Multi-device cert tests need per-role discriminator/passcode/port assignment in the device flavors before this can be supported.`
+    );
+  }
+}
+function certTest(tc, options) {
+  const controllerRoles = options.controllers ?? { dut: "dut" };
+  const deviceRoles = options.devices ?? { th: options.app };
+  const deviceRoleNames = Object.keys(deviceRoles);
+  if (deviceRoleNames.length > 1) {
+    throw new MultiDeviceUnsupportedError(tc, deviceRoleNames);
+  }
+  const definition = {
+    tc,
+    plan: options.plan,
+    pics: options.pics,
+    app: options.app,
+    steps: new Array()
+  };
+  const descriptor = {
+    kind: "cert",
+    name: tc,
+    path: tc,
+    app: options.app,
+    // PicsExpression's grammar conjoins with a single "&"; "&&" fails to parse
+    pics: options.pics.length ? options.pics.join(" & ") : void 0
+  };
+  defineCertTest(descriptor, definition, controllerRoles, deviceRoles);
+  const builder = {
+    step(number, text, run, opts) {
+      if (opts?.flavors !== void 0 && opts.flavors.length === 0) {
+        throw new Error(
+          `certTest "${tc}" step ${number} declares an empty "flavors" list, which would skip it on every flavor \u2014 omit the option instead if that's genuinely intended`
+        );
+      }
+      definition.steps.push({
+        number,
+        text,
+        run,
+        pics: opts?.pics,
+        expected: opts?.expected,
+        flavors: opts?.flavors
+      });
+      return builder;
+    }
+  };
+  return builder;
+}
+function primaryDeviceRole(deviceRoles, app) {
+  for (const [role, roleApp] of Object.entries(deviceRoles)) {
+    if (roleApp === app) {
+      return role;
+    }
+  }
+  throw new Error(`certTest options.devices has no role for app "${app}" (the app the harness activates)`);
+}
+function subjectFactoryFor(flavor, app) {
+  switch (flavor) {
+    case "chip-docker":
+      return ChipDockerSubject(app);
+    case "chip-local":
+      return ChipLocalSubject(app);
+    case "matterjs": {
+      const factory = matterJsCertSubjectFor(app);
+      if (!factory) {
+        throw new Error(
+          `No matterjs cert subject registered for app "${app}"; a consumer (e.g. support/chip-testing/src/cert/index.ts) must call registerMatterJsCertSubject(...) first`
+        );
+      }
+      return factory;
+    }
+  }
+}
+function defineCertTest(descriptor, definition, controllerRoles, deviceRoles) {
+  describe(descriptor.name, () => {
+    const flavor = resolveDeviceFlavor();
+    const primaryRole = primaryDeviceRole(deviceRoles, definition.app);
+    const factory = subjectFactoryFor(flavor, definition.app);
+    registerCertTestFactory(
+      descriptor,
+      () => new WiredCertTest(
+        definition,
+        descriptor,
+        State.container,
+        flavor,
+        primaryRole,
+        controllerRoles,
+        deviceRoles
+      )
+    );
+    State.install();
+    const test = chip.testFor(descriptor);
+    const mochaTest = it(descriptor.name, function() {
+      this.timeout(descriptor.timeoutMs ?? chip.defaultTimeoutMs);
+      return State.run(test, [], async () => {
+      });
+    });
+    beforeOne(mochaTest, async function() {
+      await State.activateSubject(factory, false, test);
+    });
+    mochaTest.descriptor = test.descriptor;
+    afterOne(mochaTest, State.deactivateSubject);
+  });
+}
+let matterJsCommitPromise;
+function matterJsCommit() {
+  matterJsCommitPromise ??= execFileAsync("git", ["rev-parse", "HEAD"]).then(({ stdout }) => stdout.trim()).catch(() => "(unknown)");
+  return matterJsCommitPromise;
+}
+async function chipRefFor(flavor, app) {
+  try {
+    switch (flavor) {
+      case "chip-docker":
+        return await chipDockerImageRevision(app);
+      case "chip-local":
+        return await chipLocalMarkerRevision();
+      case "matterjs":
+        return void 0;
+    }
+  } catch {
+    return void 0;
+  }
+}
+async function chipDockerImageRevision(app) {
+  const docker = new Docker();
+  const image = Image(docker, `${chipImageBase()}-${app}:latest`);
+  const info = await image.inspect();
+  return info.Config.Labels?.["org.opencontainers.image.revision"];
+}
+async function chipLocalMarkerRevision() {
+  const dir = await resolveChipLocalAppDir();
+  const text = await readFile(join(dir, "CHIP_REF"), "utf-8");
+  const trimmed = text.trim();
+  return trimmed === "" ? void 0 : trimmed;
+}
+function evidenceOutDir() {
+  return env.MATTER_CERT_EVIDENCE_DIR || join(process.cwd(), "cert-evidence");
+}
+function isCertDevice(subject) {
+  return "flavor" in subject && "log" in subject && "exit" in subject;
+}
+class WiredCertTest extends CertTest {
+  #flavor;
+  #primaryRole;
+  #controllerRoles;
+  #deviceRoles;
+  #cx;
+  #extraDevices = new Array();
+  #recorder;
+  constructor(definition, descriptor, container, flavor, primaryRole, controllerRoles, deviceRoles) {
+    super(definition, descriptor, container);
+    this.#flavor = flavor;
+    this.#primaryRole = primaryRole;
+    this.#controllerRoles = controllerRoles;
+    this.#deviceRoles = deviceRoles;
+  }
+  async invoke(subject, step, args, uncommissioned) {
+    const cx = await this.#buildContext(subject);
+    this.#cx = cx;
+    try {
+      await super.invoke(subject, step, args, uncommissioned);
+    } finally {
+      this.#cx = void 0;
+      await this.#teardown(cx.controllers);
+    }
+  }
+  contextFor(_subject) {
+    if (!this.#cx) {
+      throw new Error("WiredCertTest.contextFor() called outside invoke()");
+    }
+    return this.#cx;
+  }
+  async #buildContext(subject) {
+    if (!isCertDevice(subject)) {
+      throw new Error(
+        `Cert-test subject for "${this.descriptor.name}" does not implement CertDevice (missing log/flavor/exit) \u2014 its Subject.Factory must come from subjectFactoryFor()`
+      );
+    }
+    const devices = { [this.#primaryRole]: subject };
+    const extra = new Array();
+    const controllers = {};
+    try {
+      for (const [role, app] of Object.entries(this.#deviceRoles)) {
+        if (role === this.#primaryRole) {
+          continue;
+        }
+        const factory = subjectFactoryFor(this.#flavor, app);
+        const device = factory(`${this.descriptor.name}-${role}`);
+        extra.push(device);
+        await device.initialize();
+        await device.start();
+        devices[role] = device;
+      }
+      for (const name of Object.keys(this.#controllerRoles)) {
+        const controller = createControllerAdapter(name);
+        controllers[name] = controller;
+        await controller.start();
+      }
+    } catch (e) {
+      this.#extraDevices = extra;
+      await this.#teardown(controllers);
+      throw e;
+    }
+    const [matterJsRef, chipRef] = await Promise.all([
+      matterJsCommit(),
+      chipRefFor(this.#flavor, this.definition.app)
+    ]);
+    const recorder = new EvidenceRecorder(evidenceOutDir(), {
+      tc: this.definition.tc,
+      plan: this.definition.plan,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      controller: Object.keys(this.#controllerRoles).join(","),
+      device: `${this.#flavor}:${this.definition.app}`,
+      matterJsCommit: matterJsRef,
+      chipRef
+    });
+    this.#extraDevices = extra;
+    this.#recorder = recorder;
+    return { controllers, devices, recorder };
+  }
+  /**
+   * Attaches every device's and controller's accumulated log before {@link EvidenceRecorder.flush}
+   * writes it to disk. `cx.recorder` is typed as the generic `StepRecorder` (no `attachLog`), so
+   * this uses the concrete instance `#buildContext` kept a reference to instead.
+   */
+  async beforeFlush(cx) {
+    if (!this.#recorder) {
+      return;
+    }
+    for (const [role, device] of Object.entries(cx.devices)) {
+      this.#recorder.attachLog(`device-${role}`, device.log.lines);
+    }
+    for (const [name, controller] of Object.entries(cx.controllers)) {
+      this.#recorder.attachLog(`controller-${name}`, controller.log.lines);
+    }
+  }
+  async #teardown(controllers) {
+    const errors = new Array();
+    for (const controller of Object.values(controllers)) {
+      try {
+        await controller.close();
+      } catch (e) {
+        errors.push(e);
+      }
+    }
+    for (const device of this.#extraDevices) {
+      try {
+        await device.close();
+      } catch (e) {
+        errors.push(e);
+      }
+    }
+    this.#extraDevices = [];
+    this.#recorder = void 0;
+    for (const error of errors) {
+      console.warn("Error tearing down cert-test controller/device:", error);
+    }
+  }
+}
+export {
+  MultiDeviceUnsupportedError,
+  certTest
+};
+//# sourceMappingURL=cert-dsl.js.map

package/dist/esm/chip/cert/cert-dsl.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/chip/cert/cert-dsl.ts"],
+  "mappings": "AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,SAAS,gBAAgB;AACzB,SAAS,gBAAgB;AACzB,SAAS,YAAY;AACrB,SAAS,WAAW;AACpB,SAAS,iBAAiB;AAG1B,SAAS,cAAc;AACvB,SAAS,aAAa;AACtB,SAAS,UAAU,iBAAiB;AAEpC,SAAS,YAAY;AACrB,SAAS,aAAa;AACtB,SAAS,eAAe,mBAAmB,kBAAkB,8BAA8B;AAS3F,SAAS,UAAU,+BAA+B;AAClD,SAA4B,+BAA+B;AAC3D,SAAS,2BAA2B;AACpC,SAAS,wBAAwB;AACjC,SAAS,8BAA8B;AAEvC,MAAM,gBAAgB,UAAU,QAAQ;AAyCjC,MAAM,oCAAoC,MAAM;AAAA,EACnD,YAAY,IAAY,OAAiB;AACrC;AAAA,MACI,aAAa,EAAE,cAAc,MAAM,MAAM,aAAa,MAAM,KAAK,IAAI,CAAC;AAAA,IAK1E;AAAA,EACJ;AACJ;AAQO,SAAS,SAAS,IAAY,SAA2C;AAC5E,QAAM,kBAAkB,QAAQ,eAAe,EAAE,KAAK,MAAM;AAC5D,QAAM,cAAc,QAAQ,WAAW,EAAE,IAAI,QAAQ,IAAI;AAEzD,QAAM,kBAAkB,OAAO,KAAK,WAAW;AAC/C,MAAI,gBAAgB,SAAS,GAAG;AAC5B,UAAM,IAAI,4BAA4B,IAAI,eAAe;AAAA,EAC7D;AAEA,QAAM,aAAiC;AAAA,IACnC;AAAA,IACA,MAAM,QAAQ;AAAA,IACd,MAAM,QAAQ;AAAA,IACd,KAAK,QAAQ;AAAA,IACb,OAAO,IAAI,MAA0B;AAAA,EACzC;AAEA,QAAM,aAAiC;AAAA,IACnC,MAAM;AAAA,IACN,MAAM;AAAA,IACN,MAAM;AAAA,IACN,KAAK,QAAQ;AAAA;AAAA,IAEb,MAAM,QAAQ,KAAK,SAAS,QAAQ,KAAK,KAAK,KAAK,IAAI;AAAA,EAC3D;AAEA,iBAAe,YAAY,YAAY,iBAAiB,WAAW;AAEnE,QAAM,UAA2B;AAAA,IAC7B,KAAK,QAAQ,MAAM,KAAK,MAAM;AAG1B,UAAI,MAAM,YAAY,UAAa,KAAK,QAAQ,WAAW,GAAG;AAC1D,cAAM,IAAI;AAAA,UACN,aAAa,EAAE,UAAU,MAAM;AAAA,QAEnC;AAAA,MACJ;AAEA,iBAAW,MAAM,KAAK;AAAA,QAClB;AAAA,QACA;AAAA,QACA;AAAA,QACA,MAAM,MAAM;AAAA,QACZ,UAAU,MAAM;AAAA,QAChB,SAAS,MAAM;AAAA,MACnB,CAAC;AACD,aAAO;AAAA,IACX;AAAA,EACJ;AAEA,SAAO;AACX;AAEA,SAAS,kBAAkB,aAAqC,KAAqB;AACjF,aAAW,CAAC,MAAM,OAAO,KAAK,OAAO,QAAQ,WAAW,GAAG;AACvD,QAAI,YAAY,KAAK;AACjB,aAAO;AAAA,IACX;AAAA,EACJ;AACA,QAAM,IAAI,MAAM,iDAAiD,GAAG,mCAAmC;AAC3G;AAEA,SAAS,kBAAkB,QAAsB,KAAgC;AAC7E,UAAQ,QAAQ;AAAA,IACZ,KAAK;AACD,aAAO,kBAAkB,GAAG;AAAA,IAEhC,KAAK;AACD,aAAO,iBAAiB,GAAG;AAAA,IAE/B,KAAK,YAAY;AACb,YAAM,UAAU,uBAAuB,GAAG;AAC1C,UAAI,CAAC,SAAS;AACV,cAAM,IAAI;AAAA,UACN,gDAAgD,GAAG;AAAA,QAEvD;AAAA,MACJ;AACA,aAAO;AAAA,IACX;AAAA,EACJ;AACJ;AAmBA,SAAS,eACL,YACA,YACA,iBACA,aACF;AACE,WAAS,WAAW,MAAM,MAAM;AAC5B,UAAM,SAAS,oBAAoB;AACnC,UAAM,cAAc,kBAAkB,aAAa,WAAW,GAAG;AACjE,UAAM,UAAU,kBAAkB,QAAQ,WAAW,GAAG;AAExD;AAAA,MACI;AAAA,MACA,MACI,IAAI;AAAA,QACA;AAAA,QACA;AAAA,QACA,MAAM;AAAA,QACN;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,MACJ;AAAA,IACR;AAEA,UAAM,QAAQ;AACd,UAAM,OAAO,KAAK,QAAQ,UAAU;AAEpC,UAAM,YAAY,GAAG,WAAW,MAAM,WAAY;AAC9C,WAAK,QAAQ,WAAW,aAAa,KAAK,gBAAgB;AAC1D,aAAO,MAAM,IAAI,MAAM,CAAC,GAAG,YAAY;AAAA,MAAC,CAAC;AAAA,IAC7C,CAAC;AAED,cAAU,WAAW,iBAAkB;AACnC,YAAM,MAAM,gBAAgB,SAAS,OAAO,IAAI;AAAA,IACpD,CAAC;AAED,cAAU,aAAa,KAAK;AAE5B,aAAS,WAAW,MAAM,iBAAiB;AAAA,EAC/C,CAAC;AACL;AAEA,IAAI;AAGJ,SAAS,iBAAkC;AACvC,4BAA0B,cAAc,OAAO,CAAC,aAAa,MAAM,CAAC,EAC/D,KAAK,CAAC,EAAE,OAAO,MAAM,OAAO,KAAK,CAAC,EAClC,MAAM,MAAM,WAAW;AAC5B,SAAO;AACX;AAGA,eAAe,WAAW,QAAsB,KAA0C;AACtF,MAAI;AACA,YAAQ,QAAQ;AAAA,MACZ,KAAK;AACD,eAAO,MAAM,wBAAwB,GAAG;AAAA,MAC5C,KAAK;AACD,eAAO,MAAM,wBAAwB;AAAA,MACzC,KAAK;AACD,eAAO;AAAA,IACf;AAAA,EACJ,QAAQ;AACJ,WAAO;AAAA,EACX;AACJ;AAEA,eAAe,wBAAwB,KAA0C;AAC7E,QAAM,SAAS,IAAI,OAAO;AAC1B,QAAM,QAAQ,MAAM,QAAQ,GAAG,cAAc,CAAC,IAAI,GAAG,SAAS;AAC9D,QAAM,OAAO,MAAM,MAAM,QAAQ;AACjC,SAAO,KAAK,OAAO,SAAS,mCAAmC;AACnE;AAEA,eAAe,0BAAuD;AAClE,QAAM,MAAM,MAAM,uBAAuB;AACzC,QAAM,OAAO,MAAM,SAAS,KAAK,KAAK,UAAU,GAAG,OAAO;AAC1D,QAAM,UAAU,KAAK,KAAK;AAC1B,SAAO,YAAY,KAAK,SAAY;AACxC;AAQA,SAAS,iBAAyB;AAC9B,SAAO,IAAI,4BAA4B,KAAK,QAAQ,IAAI,GAAG,eAAe;AAC9E;AAOA,SAAS,aAAa,SAAyC;AAC3D,SAAO,YAAY,WAAW,SAAS,WAAW,UAAU;AAChE;AAOA,MAAM,sBAAsB,SAAS;AAAA,EACjC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,gBAAgB,IAAI,MAAkB;AAAA,EACtC;AAAA,EAEA,YACI,YACA,YACA,WACA,QACA,aACA,iBACA,aACF;AACE,UAAM,YAAY,YAAY,SAAS;AACvC,SAAK,UAAU;AACf,SAAK,eAAe;AACpB,SAAK,mBAAmB;AACxB,SAAK,eAAe;AAAA,EACxB;AAAA,EAEA,MAAe,OACX,SACA,MACA,MACA,gBACa;AACb,UAAM,KAAK,MAAM,KAAK,cAAc,OAAO;AAC3C,SAAK,MAAM;AACX,QAAI;AACA,YAAM,MAAM,OAAO,SAAS,MAAM,MAAM,cAAc;AAAA,IAC1D,UAAE;AACE,WAAK,MAAM;AACX,YAAM,KAAK,UAAU,GAAG,WAAW;AAAA,IACvC;AAAA,EACJ;AAAA,EAEmB,WAAW,UAAoC;AAC9D,QAAI,CAAC,KAAK,KAAK;AACX,YAAM,IAAI,MAAM,oDAAoD;AAAA,IACxE;AACA,WAAO,KAAK;AAAA,EAChB;AAAA,EAEA,MAAM,cAAc,SAA4C;AAC5D,QAAI,CAAC,aAAa,OAAO,GAAG;AACxB,YAAM,IAAI;AAAA,QACN,0BAA0B,KAAK,WAAW,IAAI;AAAA,MAElD;AAAA,IACJ;AAEA,UAAM,UAAsC,EAAE,CAAC,KAAK,YAAY,GAAG,QAAQ;AAC3E,UAAM,QAAQ,IAAI,MAAkB;AACpC,UAAM,cAAiD,CAAC;AAIxD,QAAI;AACA,iBAAW,CAAC,MAAM,GAAG,KAAK,OAAO,QAAQ,KAAK,YAAY,GAAG;AACzD,YAAI,SAAS,KAAK,cAAc;AAC5B;AAAA,QACJ;AACA,cAAM,UAAU,kBAAkB,KAAK,SAAS,GAAG;AACnD,cAAM,SAAS,QAAQ,GAAG,KAAK,WAAW,IAAI,IAAI,IAAI,EAAE;AACxD,cAAM,KAAK,MAAM;AACjB,cAAM,OAAO,WAAW;AACxB,cAAM,OAAO,MAAM;AACnB,gBAAQ,IAAI,IAAI;AAAA,MACpB;AAEA,iBAAW,QAAQ,OAAO,KAAK,KAAK,gBAAgB,GAAG;AACnD,cAAM,aAAa,wBAAwB,IAAI;AAC/C,oBAAY,IAAI,IAAI;AACpB,cAAM,WAAW,MAAM;AAAA,MAC3B;AAAA,IACJ,SAAS,GAAG;AACR,WAAK,gBAAgB;AACrB,YAAM,KAAK,UAAU,WAAW;AAChC,YAAM;AAAA,IACV;AAEA,UAAM,CAAC,aAAa,OAAO,IAAI,MAAM,QAAQ,IAAI;AAAA,MAC7C,eAAe;AAAA,MACf,WAAW,KAAK,SAAS,KAAK,WAAW,GAAG;AAAA,IAChD,CAAC;AAED,UAAM,WAAW,IAAI,iBAAiB,eAAe,GAAG;AAAA,MACpD,IAAI,KAAK,WAAW;AAAA,MACpB,MAAM,KAAK,WAAW;AAAA,MACtB,YAAW,oBAAI,KAAK,GAAE,YAAY;AAAA,MAClC,YAAY,OAAO,KAAK,KAAK,gBAAgB,EAAE,KAAK,GAAG;AAAA,MACvD,QAAQ,GAAG,KAAK,OAAO,IAAI,KAAK,WAAW,GAAG;AAAA,MAC9C,gBAAgB;AAAA,MAChB;AAAA,IACJ,CAAC;AAED,SAAK,gBAAgB;AACrB,SAAK,YAAY;AAEjB,WAAO,EAAE,aAAa,SAAS,SAAS;AAAA,EAC5C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAyB,YAAY,IAAoC;AACrE,QAAI,CAAC,KAAK,WAAW;AACjB;AAAA,IACJ;AACA,eAAW,CAAC,MAAM,MAAM,KAAK,OAAO,QAAQ,GAAG,OAAO,GAAG;AACrD,WAAK,UAAU,UAAU,UAAU,IAAI,IAAI,OAAO,IAAI,KAAK;AAAA,IAC/D;AACA,eAAW,CAAC,MAAM,UAAU,KAAK,OAAO,QAAQ,GAAG,WAAW,GAAG;AAC7D,WAAK,UAAU,UAAU,cAAc,IAAI,IAAI,WAAW,IAAI,KAAK;AAAA,IACvE;AAAA,EACJ;AAAA,EAEA,MAAM,UAAU,aAA+D;AAC3E,UAAM,SAAS,IAAI,MAAe;AAElC,eAAW,cAAc,OAAO,OAAO,WAAW,GAAG;AACjD,UAAI;AACA,cAAM,WAAW,MAAM;AAAA,MAC3B,SAAS,GAAG;AACR,eAAO,KAAK,CAAC;AAAA,MACjB;AAAA,IACJ;AAEA,eAAW,UAAU,KAAK,eAAe;AACrC,UAAI;AACA,cAAM,OAAO,MAAM;AAAA,MACvB,SAAS,GAAG;AACR,eAAO,KAAK,CAAC;AAAA,MACjB;AAAA,IACJ;AACA,SAAK,gBAAgB,CAAC;AACtB,SAAK,YAAY;AAEjB,eAAW,SAAS,QAAQ;AACxB,cAAQ,KAAK,mDAAmD,KAAK;AAAA,IACzE;AAAA,EACJ;AACJ;",
+  "names": []
+}

package/dist/esm/chip/cert/cert-test.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Subject } from "../../device/subject.js";
+import { BaseTest } from "../../device/test.js";
+import type { Container } from "../../docker/container.js";
+import { TestDescriptor, TestFileDescriptor } from "../../test-descriptor.js";
+import { CertStepContext, CertTestDefinition } from "./cert-context.js";
+/**
+ * Runs a cert test plan translated into {@link CertStepDefinition}s.
+ *
+ * Per-step PICS are evaluated at run time against {@link Subject.pics}, since
+ * {@link TestDescriptor.filter} only filters whole descriptors at registration time.
+ */
+export declare class CertTest extends BaseTest {
+    #private;
+    constructor(definition: CertTestDefinition, descriptor: TestFileDescriptor, container: Container);
+    get definition(): CertTestDefinition;
+    initializeSubject(_subject: Subject): Promise<void>;
+    invoke(subject: Subject, step: (title: string) => void, _args: string[], _uncommissioned: boolean): Promise<void>;
+    /**
+     * Build the step context for a run.  Overridable so controller/device wiring can be layered on in
+     * later tasks without changing {@link invoke}'s public contract.
+     */
+    protected contextFor(_subject: Subject): CertStepContext;
+    /**
+     * Runs immediately before {@link StepRecorder.flush}, after every step has settled. Overridable
+     * so wiring that built its own concrete recorder (see `WiredCertTest` in `cert-dsl.ts`) can attach
+     * final device/controller logs — `contextFor`'s generic `StepRecorder` type doesn't expose that,
+     * only the concrete recorder implementation does.
+     */
+    protected beforeFlush(_cx: CertStepContext): Promise<void>;
+}
+/**
+ * Registers the factory {@link state.ts}'s `createTest` calls when it first encounters a
+ * `"cert"`-kind descriptor. `certTest()` (`cert-dsl.ts`) calls this before the corresponding
+ * `chip.testFor(descriptor)`, so the factory is always present by the time `createTest` looks it up.
+ */
+export declare function registerCertTestFactory(descriptor: TestDescriptor, factory: () => CertTest): void;
+/**
+ * Constructs the {@link CertTest} registered for `descriptor` via {@link registerCertTestFactory}.
+ */
+export declare function createRegisteredCertTest(descriptor: TestDescriptor): CertTest;
+//# sourceMappingURL=cert-test.d.ts.map

package/dist/esm/chip/cert/cert-test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cert-test.d.ts","sourceRoot":"","sources":["../../../../src/chip/cert/cert-test.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAG9E,OAAO,EAEH,eAAe,EAEf,kBAAkB,EAMrB,MAAM,mBAAmB,CAAC;AAa3B;;;;;GAKG;AACH,qBAAa,QAAS,SAAQ,QAAQ;;IAGlC,YAAY,UAAU,EAAE,kBAAkB,EAAE,UAAU,EAAE,kBAAkB,EAAE,SAAS,EAAE,SAAS,EAG/F;IAED,IAAI,UAAU,uBAEb;IAEK,iBAAiB,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAExD;IAEK,MAAM,CACR,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,EAC7B,KAAK,EAAE,MAAM,EAAE,EACf,eAAe,EAAE,OAAO,GACzB,OAAO,CAAC,IAAI,CAAC,CAyFf;IAED;;;OAGG;IACH,SAAS,CAAC,UAAU,CAAC,QAAQ,EAAE,OAAO,GAAG,eAAe,CAMvD;IAED;;;;;OAKG;IACH,UAAgB,WAAW,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAG;CACtE;AAyKD;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,QAAQ,GAAG,IAAI,CAEjG;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,cAAc,GAAG,QAAQ,CAM7E"}