@matter/testing 0.13.1-alpha.0-20250501-80c86b03e → 0.13.1-alpha.0-20250504-87f265a2e

package/src/chip/container-command-pipe.ts

@@ -19,21 +19,22 @@ export class ContainerCommandPipe extends CommandPipe {
     #deactivate?: () => void;
     #stopped?: Promise<void>;
 
-    constructor(container: Container, subject: BackchannelCommand.Subject, appName: string) {
-        super(subject, appName);
+    constructor(container: Container, subject: BackchannelCommand.Subject) {
+        super(subject, "/command-pipe.fifo");
         this.#container = container;
     }
 
     override async initialize() {
-        // Many test files are hard-coded to /tmp so we swap out temp files to preserve state when we switch test
-        // agents.  This would overwrite our FIFO, however, so we symlink to the real FIFO to prevent it from being
-        // overwritten
+        // We create a single FIFO for the container and symlink to the hard-coded name expected by CHIP
         await this.#container.createPipe(FIFO_PATH);
-        await this.#container.exec(["ln", "-sf", "/command-pipe.fifo", this.filename]);
 
         this.#stopped = this.#processCommands();
     }
 
+    async installForApp(name: string) {
+        await this.#container.exec(["ln", "-sf", this.filename, ContainerCommandPipe.filenameFor(name)]);
+    }
+
     override async close() {
         this.#deactivate?.();
         this.#deactivate = undefined;
@@ -43,39 +44,36 @@ export class ContainerCommandPipe extends CommandPipe {
     }
 
     async #processCommands() {
-        let terminal: Terminal<string> | undefined;
+        let commands: Terminal<string> | undefined;
         try {
-            terminal = await this.#container.follow(FIFO_PATH);
+            commands = await this.#container.exec(
+                ["bash", "-c", `while true; do cat ${FIFO_PATH}; done`],
+                Terminal.StdoutLine,
+            );
 
-            const iterator = terminal[Symbol.asyncIterator]();
-
-            while (true) {
-                let deactivator;
-                const deactivated = new Promise<void>(resolve => {
-                    deactivator = this.#deactivate = resolve;
-                });
+            const deactivated = new Promise<void>(resolve => {
+                this.#deactivate = resolve;
+            });
 
-                const iteration = iterator.next().then(result => result.value as undefined | string);
+            const iterator = commands[Symbol.asyncIterator]();
 
-                try {
-                    const line = await Promise.race([deactivated, iteration]);
-                    if (line === undefined) {
-                        break;
-                    }
-
-                    this.onData(line);
-                } finally {
-                    if (this.#deactivate === deactivator) {
-                        this.#deactivate = undefined;
-                    }
+            while (true) {
+                const command = await Promise.race([
+                    deactivated,
+                    iterator.next().then(result => result.value as string),
+                ]);
+                if (command === undefined) {
+                    break;
                 }
+                this.onData(command);
             }
+            await deactivated;
         } finally {
-            if (terminal) {
+            if (commands) {
                 try {
-                    await terminal.close();
+                    await commands.close();
                 } catch (e) {
-                    console.warn(`Error closing FIFO listener for ${this.filename}:`, e);
+                    console.warn(`Error closing command proxy for ${this.filename}:`, e);
                 }
             }
 

package/src/chip/index.ts

@@ -6,4 +6,4 @@
 
 export * from "./chip.js";
 export * from "./command-pipe.js";
-export * from "./pics-expression.js";
+export * from "./pics/index.js";

package/src/chip/matter-js-pics.properties

@@ -24,7 +24,7 @@ DGGEN.S.A0006=0
 DGGEN.S.A0007=0
 
 # We do not support the "TestTrigger" command
-| DGGEN.S.C00.Rsp=0
+DGGEN.S.C00.Rsp=0
 
 # We do not support the "TimeSnapshotResponse" command
 DGGEN.S.C03.Rsp=0
@@ -40,9 +40,12 @@ DGGEN.S.F00=0
 # We do not support the optional Battery Fault Change event
 PS.S.E01=0
 
-# We use an Ethernet Network commissioning cluster and so we do not have these two attributes
+# We don't support ScanMaxTimeSeconds or ConnectMaxTimeSeconds attributes
 CNET.S.A0002..3=0
 
+# We don't support ethernet networking
+CNET.S.F02=0
+
 # We do not provide a Taglist on Descriptor cluster
 DESC.S.F00=0
 
@@ -55,8 +58,8 @@ BOOL.S.E00=1
 # We support "reachable" event on Basic Information
 BINFO.S.A0011=1
 
-# We don't support ScanMaxTimeSeconds or ConnectMaxTimeSeconds attributes
-CNET.S.A0002..3=0
+# We do not support ConfigurationVersion attribute on Basic Information
+BINFO.S.A0018=0
 
 # No level related features for CO2 measurement
 CDOCONC.S.F01..3=0

package/src/chip/{pics-expression.ts → pics/expression.ts}

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { PicsFile } from "./pics-file.js";
+import { PicsFile } from "./file.js";
 
 /**
  * A set of PICS specifiers, each of which must be true for the set to apply.
@@ -112,7 +112,8 @@ function parse(definition: string) {
 
     const result = parseExpr();
 
-    if (tokenizer.peek() !== undefined) {
+    // Note - allow garbage trailing "(" as this seems to be a way to provide a hint as to purpose of expression
+    if (tokenizer.peek() !== undefined && tokenizer.peek()?.kind !== "(") {
         throw new InvalidPicsExpressionError(definition, tokenizer.peek());
     }
 
@@ -191,7 +192,7 @@ function test(ast: Ast, file: PicsFile): boolean {
             return !test(ast.operand, file);
 
         case "name":
-            return file.values[ast.name] === "1";
+            return file.values[ast.name] === 1;
 
         case "&":
             return test(ast.lhs, file) && test(ast.rhs, file);

package/src/chip/{pics-file.ts → pics/file.ts}

@@ -4,10 +4,10 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { readFileSync, writeFileSync } from "node:fs";
+import { PicsValues } from "./values.js";
 
 /**
- * Manages Matter PICS files.
+ * In-memory Matter PICS file.
  *
  * Supports extended syntax for defining ranges of values of the form "NAMExx..yy=*" where xx and yy are hexadecimal
  * numbers specifying the start and end of a range (inclusive).  These are expanded in {@link patch} which modifies the
@@ -18,13 +18,14 @@ import { readFileSync, writeFileSync } from "node:fs";
  */
 export class PicsFile {
     #lines: string[];
-    #values?: Record<string, string>;
+    #values?: PicsValues;
 
-    constructor(pathOrBody: string, inline = false) {
-        if (inline === false) {
-            pathOrBody = readFileSync(pathOrBody, "utf-8");
+    constructor(lines?: string | string[]) {
+        if (typeof lines === "string") {
+            this.#lines = lines.split("\n").map(l => l.trim());
+        } else {
+            this.#lines = lines ?? [];
         }
-        this.#lines = pathOrBody.split("\n").map(l => l.trim());
     }
 
     get lines() {
@@ -33,7 +34,7 @@ export class PicsFile {
 
     get values() {
         if (!this.#values) {
-            const values = {} as Record<string, string>;
+            const values = {} as PicsValues;
             for (const line of this.lines) {
                 parseLine(line, values);
             }
@@ -51,7 +52,7 @@ export class PicsFile {
 
         const newLines = new Array<string>();
         for (const line of this.lines) {
-            const lineValues = {} as Record<string, string>;
+            const lineValues = {} as PicsValues;
             if (!parseLine(line, lineValues)) {
                 newLines.push(line);
                 continue;
@@ -75,13 +76,15 @@ export class PicsFile {
         this.#values = undefined;
         this.#lines = newLines;
     }
+}
 
-    save(path: string) {
-        writeFileSync(path, this.toString());
+export namespace PicsFile {
+    export interface Values {
+        [key: string]: 0 | 1;
     }
 }
 
-function parseLine(line: string, values: Record<string, string>): boolean {
+function parseLine(line: string, values: PicsValues): boolean {
     line = line.trim();
     if (line.startsWith("#")) {
         return false;
@@ -92,7 +95,21 @@ function parseLine(line: string, values: Record<string, string>): boolean {
         return false;
     }
 
-    const [, key, value] = valueMatch;
+    const [, key, valueStr] = valueMatch;
+    let value: 0 | 1;
+    switch (valueStr) {
+        case "0":
+            value = 0;
+            break;
+
+        case "1":
+            value = 1;
+            break;
+
+        default:
+            return false;
+    }
+
     const rangeMatch = key.match(/^(\S+)\.\.([\da-f]+)$/i);
     if (!rangeMatch) {
         values[key] = value;

package/src/chip/pics/index.ts

@@ -0,0 +1,10 @@
+/**
+ * @license
+ * Copyright 2022-2025 Project CHIP Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./expression.js";
+export * from "./file.js";
+export * from "./source.js";
+export * from "./values.js";

package/src/chip/pics/source.ts

@@ -0,0 +1,163 @@
+/**
+ * @license
+ * Copyright 2022-2025 Project CHIP Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Package } from "#tools";
+import { readFile } from "node:fs/promises";
+import { isAbsolute } from "node:path";
+import { State } from "../state.js";
+import { PicsFile } from "./file.js";
+
+const dataCache = new WeakMap<PicsSource, PicsFile>();
+const filenameCache = new WeakMap<PicsFile, string>();
+
+let nextFileNo = 1;
+
+/**
+ * Source of PICS values.
+ */
+export type PicsSource =
+    | PicsSource.Composite
+    | PicsSource.ChipFile
+    | PicsSource.LocalFile
+    | PicsSource.Lines
+    | PicsSource.Values;
+
+export namespace PicsSource {
+    /**
+     * Load a {@link PicsFile} defined by a {@link PicsSource}.
+     *
+     * Caches results so a source always returns the same {@link PicsFile} instance.
+     */
+    export async function load(source: PicsSource): Promise<PicsFile> {
+        let file = dataCache.get(source);
+        if (file) {
+            return file;
+        }
+
+        switch (source.kind) {
+            case "composite":
+                for (const subsource of source.sources) {
+                    const sourceFile = await load(subsource);
+                    if (file) {
+                        file.patch(sourceFile);
+                    } else {
+                        file = sourceFile;
+                    }
+                }
+                if (!file) {
+                    file = new PicsFile();
+                }
+                break;
+
+            case "chip":
+                file = new PicsFile(await State.container.read(source.name));
+                break;
+
+            case "file":
+                file = new PicsFile(await readFile(resolve(source.name), "utf-8"));
+                break;
+
+            case "lines":
+                file = new PicsFile(source.lines.split("\n").map(l => l.trim()));
+                break;
+
+            case "values":
+                file = new PicsFile(Object.entries(source.values).map(([key, value]) => `${key}=${value}`));
+                break;
+
+            default:
+                throw new Error(`Invalid PICS source kind "${(source as { kind: unknown }).kind}"`);
+        }
+
+        dataCache.set(source, file);
+
+        return file;
+    }
+
+    /**
+     * Save a {@link PicsFile} to the a {@link ChipFile} or {@link LocalFile}.
+     */
+    export async function save(target: ChipFile | LocalFile, file: PicsFile): Promise<void> {
+        switch (target.kind) {
+            case "chip":
+                await State.container.write(target.name, file.toString());
+                break;
+
+            case "file":
+                await State.container.write(resolve(target.name), file.toString());
+                break;
+
+            default:
+                throw new Error(`Invalid PICS target kind "${(target as { kind: unknown }).kind}"`);
+        }
+    }
+
+    /**
+     * Install a {@link PicsSource} into the test container.
+     *
+     * Returns the name of the file in the container.
+     *
+     * Results are cached so the same source always returns the same filename.
+     */
+    export async function install(file: PicsFile): Promise<string> {
+        let filename = filenameCache.get(file);
+        if (filename) {
+            return filename;
+        }
+
+        filename = `/pics-${nextFileNo++}.properties`;
+
+        try {
+            filenameCache.set(file, filename);
+            await save({ kind: "chip", name: filename }, file);
+        } catch (e) {
+            filenameCache.delete(file);
+            throw e;
+        }
+
+        return filename;
+    }
+
+    export interface Composite {
+        kind: "composite";
+        sources: Source[];
+    }
+
+    export interface ChipFile {
+        kind: "chip";
+        name: string;
+    }
+
+    export interface LocalFile {
+        kind: "file";
+        name: string;
+    }
+
+    export interface Lines {
+        kind: "lines";
+        lines: string;
+    }
+
+    export interface Values {
+        kind: "values";
+        values: Record<string, 0 | 1>;
+    }
+
+    export type Source = ChipFile | LocalFile | Lines | Values;
+}
+
+function resolve(path: string): string {
+    if (isAbsolute(path)) {
+        return path;
+    }
+
+    const testing = Package.tools.findPackage("@matter/testing");
+    if (testing.hasFile(path)) {
+        return testing.resolve(path);
+    }
+
+    return resolve(path);
+}

package/src/chip/pics/values.ts

@@ -0,0 +1,9 @@
+/**
+ * @license
+ * Copyright 2022-2025 Project CHIP Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export interface PicsValues {
+    [name: string]: 0 | 1;
+}

package/src/chip/python-test.ts

@@ -11,6 +11,7 @@ import { Terminal } from "../docker/terminal.js";
 import { TestFileDescriptor } from "../test-descriptor.js";
 import { parseStep } from "./chip-test-common.js";
 import { Constants, ContainerPaths } from "./config.js";
+import { PicsSource } from "./pics/source.js";
 
 export class PythonTest extends BaseTest {
     /**
@@ -173,11 +174,12 @@ async function createCommand(descriptor: TestFileDescriptor, subject: Subject, e
     const command = ["python3", descriptor.path, ...Constants.PythonRunnerArgs];
 
     const args = scriptArgsOf(descriptor);
-    if (args !== undefined) {
-        command.push(...args);
-    }
 
-    command.push(...extraArgs);
+    command.push(...args, ...extraArgs);
+
+    if (!command.includes("--PICS")) {
+        command.push("--PICS", await PicsSource.install(subject.pics));
+    }
 
     const qrCodePos = command.indexOf("--qr-code");
     if (qrCodePos !== -1) {
@@ -188,13 +190,18 @@ async function createCommand(descriptor: TestFileDescriptor, subject: Subject, e
 }
 
 function scriptArgsOf(descriptor: TestFileDescriptor) {
-    const scriptArgs = descriptor.config?.["script-args"];
-    if (typeof scriptArgs !== "string") {
-        return;
+    let args: string[] | undefined;
+
+    const predefined = descriptor.config?.["script-args"];
+    if (typeof predefined === "string") {
+        args = predefined.trim().split(/\s+/);
+    } else if (Array.isArray(predefined)) {
+        args = [...predefined];
+    }
+
+    if (descriptor.subpath) {
+        (args ?? (args = [])).push("--test-case", descriptor.subpath);
     }
 
-    return scriptArgs
-        .replace(/--(?:storage-path|commissioning-method|discriminator|passcode|trace-to|PICS)\s+\S+\s+/g, "")
-        .trim()
-        .split(/\s+/);
+    return args ?? [];
 }

package/src/chip/state.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { ansi, Package } from "#tools";
+import { ansi } from "#tools";
 import { BackchannelCommand } from "../device/backchannel.js";
 import { Subject } from "../device/subject.js";
 import { Test } from "../device/test.js";
@@ -15,12 +15,13 @@ import { Image } from "../docker/image.js";
 import { Volume } from "../docker/volume.js";
 import { afterRun, beforeRun } from "../mocha.js";
 import type { TestRunner } from "../runner.js";
-import { TestDescriptor, TestFileDescriptor } from "../test-descriptor.js";
+import { RootTestDescriptor, TestDescriptor, TestFileDescriptor } from "../test-descriptor.js";
 import { AccessoryServer } from "./accessory-server.js";
 import type { chip } from "./chip.js";
 import { Constants, ContainerPaths } from "./config.js";
 import { ContainerCommandPipe } from "./container-command-pipe.js";
-import { PicsFile } from "./pics-file.js";
+import { PicsFile } from "./pics/file.js";
+import { PicsSource } from "./pics/source.js";
 import { PythonTest } from "./python-test.js";
 import { YamlTest } from "./yaml-test.js";
 
@@ -35,18 +36,19 @@ const Values = {
     test: undefined as Test | undefined,
     mainContainer: undefined as Container | undefined,
     mdnsContainer: undefined as Container | undefined,
-    pics: undefined as PicsFile | undefined,
+    defaultPics: undefined as PicsFile | undefined,
+    defaultPicsFilename: undefined as string | undefined,
     tests: undefined as TestDescriptor.Filesystem | undefined,
     initializedSubjects: new WeakSet<Subject>(),
     activeSubject: undefined as Subject | undefined,
     singleUseSubject: false,
-    activePipes: new Set<string>(),
     closers: Array<() => Promise<void>>(),
     subjects: new Map<Subject.Factory, Record<string, Subject>>(),
     snapshots: new Map<Subject, {}>(),
     containerLifecycleInstalled: false,
     testMap: new Map<TestDescriptor, Test>(),
     pullBeforeTesting: true,
+    commandPipe: undefined as ContainerCommandPipe | undefined,
 };
 
 /**
@@ -113,12 +115,20 @@ export const State = {
         Values.pullBeforeTesting = value;
     },
 
-    get pics() {
-        if (Values.pics === undefined) {
+    get defaultPics() {
+        if (Values.defaultPics === undefined) {
             throw new Error("PICS not initialized");
         }
 
-        return Values.pics;
+        return Values.defaultPics;
+    },
+
+    get defaultPicsFilename() {
+        if (Values.defaultPicsFilename === undefined) {
+            throw new Error("PICS not initialized");
+        }
+
+        return Values.defaultPicsFilename;
     },
 
     get tests() {
@@ -152,7 +162,7 @@ export const State = {
 
         progress.update("Initializing containers");
         try {
-            const result = await initialize();
+            await initialize();
 
             const image = await State.container.image;
             const info = await image.inspect();
@@ -163,8 +173,6 @@ export const State = {
             progress.success(
                 `Initialized CHIP ${ansi.bold(chipCommit)} image ${ansi.bold(imageVersion)} for ${ansi.bold(arch)}`,
             );
-
-            return result;
         } catch (e) {
             progress.failure("Initializing containers");
             throw e;
@@ -240,20 +248,16 @@ export const State = {
      * Open a back-channel command pipe.
      */
     async openPipe(name: string) {
-        if (Values.activePipes.has(name)) {
-            return;
+        if (Values.commandPipe === undefined) {
+            Values.commandPipe = new ContainerCommandPipe(State.container, this);
+            await Values.commandPipe.initialize();
+            State.onClose(async () => {
+                await Values.commandPipe?.close();
+                Values.commandPipe = undefined;
+            });
         }
 
-        const pipe = new ContainerCommandPipe(State.container, this, name);
-
-        await pipe.initialize();
-
-        Values.activePipes.add(name);
-
-        State.onClose(async () => {
-            await pipe.close();
-            Values.activePipes.delete(name);
-        });
+        await Values.commandPipe.installForApp(name);
     },
 
     /**
@@ -402,6 +406,7 @@ export const State = {
  */
 async function initialize() {
     await configureContainer();
+    await configureScripts();
     await configurePics();
     await configureTests();
     await configureNetwork();
@@ -465,19 +470,29 @@ async function configureContainer() {
 }
 
 /**
- * Create a PICS file in the container appropriate for matter.js.
+ * Monkey patch test scripts to work around bugs.
  */
-async function configurePics() {
-    const ciPics = await State.container.read(ContainerPaths.chipPics);
-    const pics = new PicsFile(ciPics, true);
+async function configureScripts() {
+    // There is no ack on the command pipe.  Writing to it is copied in a multitude of places (pending PR fixes some of
+    // this).  Most places have a delay to try to compensate for lack of ack but in the "centralized" command writer the
+    // delay is only 1 ms. which is sometimes too short for us.  Change to 20ms
+    await State.container.edit(
+        edit.sed("s/sleep(0.001)/sleep(.02)/"),
 
-    const testing = Package.tools.findPackage("@matter/testing");
-    const overrides = new PicsFile(testing.resolve(Constants.localPicsOverrideFile));
-    pics.patch(overrides);
+        // This is the one we actually use
+        "/usr/local/lib/python3.12/dist-packages/chip/testing/matter_testing.py",
 
-    Values.pics = pics;
+        // Patching here too just for completeness
+        "/src/python_testing/matter_testing_infrastructure/chip/testing/matter_testing.py",
+    );
+}
 
-    await State.container.write(ContainerPaths.matterJsPics, pics.toString());
+/**
+ * Create a PICS file in the container appropriate for matter.js.
+ */
+async function configurePics() {
+    Values.defaultPics = await PicsSource.load(Constants.defaultPics);
+    Values.defaultPicsFilename = await PicsSource.install(Values.defaultPics);
 }
 
 /**
@@ -487,10 +502,18 @@ async function configureTests() {
     const { container } = State;
 
     // Load test descriptors
-    const descriptor = JSON.parse(await container.read(ContainerPaths.descriptorFile)) as TestDescriptor;
+    const descriptor = JSON.parse(await container.read(ContainerPaths.descriptorFile)) as RootTestDescriptor;
+
+    // Ensure this is a supported container version
+    if (descriptor.format !== TestDescriptor.CURRENT_FORMAT) {
+        throw new Error(`Invalid descriptor format "${descriptor.format}" (expected ${TestDescriptor.CURRENT_FORMAT})`);
+    }
+
+    // Ensure test descriptor isn't empty
     if (!Array.isArray(descriptor.members)) {
         throw new Error(`CHIP test descriptor has no members`);
     }
+
     Values.tests = TestDescriptor.Filesystem(descriptor);
 }