integration-tests

name: integration-tests description: Guide for writing integration tests that verify CC interview behavior and runtime functionality using mock nodes. Use when user asks for help writing tests for a specific CC or feature.

Writing CC Integration Tests

This skill guides the creation of integration tests for Z-Wave Command Classes using the mock driver/controller/node infrastructure.

Reference Documents

• Test Patterns - Common assertion and setup patterns with examples

Overview

Integration tests verify CC behavior with a real driver instance talking to mock Z-Wave devices. The framework provides:

• A real Driver instance connected to a mock serial port
• A MockController that simulates the Z-Wave controller
• One or more MockNode instances that simulate end devices
• Auto-registered behaviors for all implemented CCs (including interview responses)

Test location: packages/zwave-js/src/lib/test/cc-specific/

Test runner: vitest (run with yarn test:ts <file>)

Reference tests:

• Simple post-interview value check: soundSwitchInterviewValueChangeOptions.test.ts
• Post-interview API command verification: userCodeCorrectCommandByVersion.test.ts
• State pre-population + unsolicited report handling: clearUserCodesOnNotification.test.ts
• Interview frame verification: secureNodeSecureEndpoint.test.ts (in test/compliance/)

Test Lifecycle

Understanding the lifecycle is critical for writing correct tests:

1. Driver starts and connects to the mock serial port
2. Mock controller and node(s) are created with specified capabilities
3. customSetup callback runs (if provided) — use this to add custom behaviors or pre-populate mock node state
4. Driver discovers the node and begins the full interview process
5. Interview completes — the node emits the "ready" event
6. Recorded frames are cleared (by default) — so testBody only sees post-interview frames
7. testBody runs with access to (t, driver, node, mockController, mockNode)
8. Cleanup — driver is destroyed, temp cache directory removed

Key implication: By default, you cannot assert on frames sent during the interview from testBody. To inspect interview frames, set clearMessageStatsBeforeTest: false.

Single-Node Test Harness

Most tests use the single-node harness from integrationTestSuite.ts:

import { CommandClasses } from "@zwave-js/core";
import { ccCaps } from "@zwave-js/testing";
import { integrationTest } from "../integrationTestSuite.js";

integrationTest("Description of what is being tested", {
    // debug: true,  // Uncomment for driver logs in temp dir

    nodeCapabilities: {
        commandClasses: [
            ccCaps({
                ccId: CommandClasses["My CC"],
                isSupported: true,
                version: 2,
                // CC-specific capabilities (type-checked via CCIdToCapabilities)
                someCapability: true,
            }),
        ],
    },

    testBody: async (t, driver, node, mockController, mockNode) => {
        // Test assertions go here
    },
});

Options

Multi-Node Test Harness

For tests requiring multiple mock nodes, use integrationTestSuiteMulti.ts:

import { integrationTest } from "../integrationTestSuiteMulti.js";

integrationTest("Multi-node test", {
    nodeCapabilities: [
        { id: 2, capabilities: { commandClasses: [/* ... */] } },
        { id: 3, capabilities: { commandClasses: [/* ... */] } },
    ],

    testBody: async (t, driver, nodes, mockController, mockNodes) => {
        // nodes[0] = ZWaveNode for id 2, nodes[1] = ZWaveNode for id 3
        // mockNodes[0] = MockNode for id 2, etc.
    },
});

Defining Node Capabilities

Basic CC list

nodeCapabilities: {
    commandClasses: [
        CommandClasses.Version,              // Just the CC ID (defaults)
        CommandClasses["Binary Switch"],      // Another basic CC
    ],
}

CC with specific capabilities using ccCaps()

The ccCaps() helper provides type-checked CC-specific capabilities:

import { ccCaps } from "@zwave-js/testing";

nodeCapabilities: {
    commandClasses: [
        ccCaps({
            ccId: CommandClasses["User Credential"],
            isSupported: true,
            version: 1,
            // Fields from UserCredentialCCCapabilities:
            numberOfSupportedUsers: 10,
            supportedCredentialRules: [UserCredentialRule.Single],
            maxUserNameLength: 32,
            supportsAllUsersChecksum: true,
            supportsUserChecksum: true,
            supportsAdminCode: true,
            supportsAdminCodeDeactivation: true,
            supportedCredentialTypes: new Map([
                [UserCredentialType.PINCode, {
                    numberOfCredentialSlots: 10,
                    minCredentialLength: 4,
                    maxCredentialLength: 10,
                    maxCredentialHashLength: 0,
                    supportsCredentialLearn: false,
                }],
            ]),
        }),
    ],
}

Capability types are defined in packages/testing/src/CCSpecificCapabilities.ts. Each CC maps its CommandClasses ID to a capabilities interface. Mock behaviors merge these with defaults at runtime.

Endpoints

nodeCapabilities: {
    commandClasses: [/* root CCs */],
    endpoints: [
        {
            commandClasses: [
                ccCaps({ ccId: CommandClasses["Binary Switch"], isSupported: true }),
            ],
        },
    ],
}

Mock Node State and Behaviors

Default Behaviors

createDefaultMockNodeBehaviors() is automatically called for every mock node. This registers handlers for all implemented CCs, including:

• Version CC queries
• All CC-specific Get → Report handlers
• Interview support (capabilities queries, user/credential enumeration, etc.)

Default behaviors are defined in packages/zwave-js/src/lib/node/mockCCBehaviors/. Each CC has its own file exporting an array of MockNodeBehavior objects.

Pre-populating Mock Node State

Mock nodes use a state map (MockNode.state) to store runtime data. CC behaviors read/write this state. To pre-populate data before the interview, use customSetup:

customSetup: async (driver, controller, mockNode) => {
    // Pre-populate a user on the mock node (UserCredential CC)
    mockNode.state.set("UserCredential_user_1", {
        userType: UserCredentialUserType.General,
        active: true,
        credentialRule: UserCredentialRule.Single,
        expiringTimeoutMinutes: 0,
        nameEncoding: UserCredentialNameEncoding.ASCII,
        userName: "Test User",
        modifierType: UserCredentialModifierType.Locally,
        modifierNodeId: 0,
    });

    // Pre-populate a credential
    mockNode.state.set("UserCredential_cred_1_1_1", {
        credentialData: Bytes.from("1234", "ascii"),
        modifierType: UserCredentialModifierType.Locally,
        modifierNodeId: 0,
    });
},

State key format varies by CC — check the mock behavior file for the StateKeys object or helper functions.

Overriding Behaviors

Behaviors added via mockNode.defineBehavior() are prepended (higher priority):

customSetup: async (driver, controller, mockNode) => {
    const customBehavior: MockNodeBehavior = {
        handleCC(controller, self, receivedCC) {
            if (receivedCC instanceof SomeCCGet) {
                // Return a custom response
                const cc = new SomeCCReport({
                    nodeId: controller.ownNodeId,
                    value: 42,
                });
                return { action: "sendCC", cc };
            }
            // Return undefined to fall through to default behaviors
        },
    };
    mockNode.defineBehavior(customBehavior);
},

Behavior return values:

Assertion Patterns

Verify Post-Interview Values

testBody: async (t, driver, node, mockController, mockNode) => {
    // Check a specific value was stored
    const valueId = SomeCCValues.someValue.id;
    t.expect(node.getValue(valueId)).toBe(expectedValue);

    // Check value metadata
    const meta = node.getValueMetadata(valueId);
    t.expect(meta.label).toBe("Expected Label");

    // Check defined value IDs
    const defined = node.getDefinedValueIDs();
    const found = defined.find((v) => SomeCCValues.someValue.is(v));
    t.expect(found).toBeDefined();
},

Verify Commands Sent During Interview

IMPORTANT: The receivedControllerFrames and sentControllerFrames arrays on MockNode are private. Do NOT access them directly. Always use the assertReceivedControllerFrame() / assertSentControllerFrame() methods instead.

Set clearMessageStatsBeforeTest: false to preserve interview frames:

integrationTest("Interview sends the expected commands", {
    clearMessageStatsBeforeTest: false,
    nodeCapabilities: {/* ... */},

    testBody: async (t, driver, node, mockController, mockNode) => {
        // Assert a specific command WAS sent
        mockNode.assertReceivedControllerFrame(
            (frame) =>
                frame.type === MockZWaveFrameType.Request
                && frame.payload instanceof UserCredentialCCUserCapabilitiesGet,
            {
                errorMessage: "Should have sent UserCapabilitiesGet",
            },
        );

        // Assert a specific command was NOT sent
        mockNode.assertReceivedControllerFrame(
            (frame) =>
                frame.type === MockZWaveFrameType.Request
                && frame.payload instanceof SomeUnexpectedCommand,
            {
                noMatch: true,
                errorMessage: "Should NOT have sent this command",
            },
        );
    },
});

Verify Post-Interview API Commands

With default clearMessageStatsBeforeTest: true, frames from the test body are recorded:

testBody: async (t, driver, node, mockController, mockNode) => {
    const api = node.commandClasses["User Credential"];
    await api.someMethod(args);

    mockNode.assertReceivedControllerFrame(
        (frame) =>
            frame.type === MockZWaveFrameType.Request
            && frame.payload instanceof ExpectedCCCommand,
        {
            errorMessage: "Expected command was not sent",
        },
    );
},

Send Unsolicited Reports to the Driver

import { createMockZWaveRequestFrame } from "@zwave-js/testing";

testBody: async (t, driver, node, mockController, mockNode) => {
    const cc = new NotificationCCReport({
        nodeId: mockNode.id,
        notificationType: 0x06,
        notificationEvent: 0x0b,
    });
    await mockNode.sendToController(createMockZWaveRequestFrame(cc));

    // Wait for processing
    await wait(100);

    // Assert effect of the report
    t.expect(node.getValue(someValueId)).toBe(expectedValue);
},

Pre-populate the Driver's Value Cache

testBody: async (t, driver, node, mockController, mockNode) => {
    // Manually seed the value DB (simulates prior interview state)
    const valueId = SomeCCValues.someValue(1).endpoint(0);
    node.valueDB.setValue(valueId, "some-value");

    // Verify it's stored
    t.expect(node.getValue(valueId)).toBe("some-value");
},

Common Imports

// Test harness
import { integrationTest } from "../integrationTestSuite.js";

// CC-specific classes and values
import { SomeCCValues } from "@zwave-js/cc/SomeCC";
import { SomeCCGet, SomeCCReport, SomeCCSet } from "@zwave-js/cc/SomeCC";

// Enums and types from the CC (re-exported through safe entrypoint)
import { AnotherEnum, SomeEnum } from "@zwave-js/cc";

// Core types
import { CommandClasses } from "@zwave-js/core";

// Testing utilities
import {
    MockZWaveFrameType,
    ccCaps,
    createMockZWaveRequestFrame,
} from "@zwave-js/testing";
import type { MockNodeBehavior } from "@zwave-js/testing";

// For buffer data
import { Bytes } from "@zwave-js/shared";

// For waiting
import { wait } from "alcalzone-shared/async";

Import conventions:

• CC class constructors (e.g. UserCredentialCCUserGet): import from @zwave-js/cc/UserCredentialCC
• CC Values (e.g. UserCredentialCCValues): import from @zwave-js/cc/UserCredentialCC
• Enums (e.g. UserCredentialType, UserCredentialRule): import from @zwave-js/cc
• CommandClasses, core types: import from @zwave-js/core
• MockZWaveFrameType, ccCaps, createMockZWaveRequestFrame, MockNodeBehavior: import from @zwave-js/testing

File Naming

Test files go in packages/zwave-js/src/lib/test/cc-specific/ and follow the pattern:

<descriptiveCamelCaseName>.test.ts

Examples:

• userCredentialInterview.test.ts
• soundSwitchInterviewValueChangeOptions.test.ts
• clearUserCodesOnNotification.test.ts

Checklist for New Integration Test

1. Determine what to test

   • Interview behavior (commands sent, values stored)
   • Post-interview API behavior
   • Unsolicited report handling
   • Edge cases (timeouts, missing capabilities, version differences)

2. Set up the test

   • Choose single-node or multi-node harness
   • Define nodeCapabilities with ccCaps() for type safety
   • Add customSetup if mock node state needs pre-population
   • Set clearMessageStatsBeforeTest: false if verifying interview frames

3. Write assertions

   • Use node.getValue() / node.getValueMetadata() for value checks
   • Use mockNode.assertReceivedControllerFrame() for command checks
   • Use createMockZWaveRequestFrame() + mockNode.sendToController() for unsolicited reports

4. Run and validate

   • yarn test:ts <test-file-path>
   • yarn fmt