README
¶
Matter Integration Tests
This directory contains integration tests for the Matter Go stack.
Test Types
1. Basic Tests (light_basic_test.go)
Basic tests verify device functionality without network I/O.
Run with:
go test ./test/integration -run TestBasic
2. End-to-End Tests (light_e2e_test.go, commissioning_e2e_test.go)
End-to-end tests verify full controller ↔ device communication over a virtual pipe network.
Run with:
go test ./test/integration -run TestE2E
3. Interop Tests (light_interop_test.go)
Interop tests verify compatibility with the official C++ SDK chip-tool.
These tests:
- Build and run the actual device binary (
cmd/matter-light-device) - Use chip-tool to commission and control the device
- Test real UDP network communication
Prerequisites:
- chip-tool must be installed and available in PATH
- Install from snap:
sudo snap install chip-tool - Or build from source: https://github.com/project-chip/connectedhomeip
Run with:
go test -tags=interop ./test/integration -run TestInterop
Run specific test:
go test -tags=interop ./test/integration -run TestInterop_LightOnOffControl -v
Test Infrastructure
Framework Package (framework/)
The framework package provides utilities for integration testing:
process.go - Device Process Management
Manages the lifecycle of Matter device binaries:
device := framework.NewDeviceProcess(framework.DeviceProcessConfig{
BinaryPath: "cmd/matter-light-device",
Port: 5540,
StoragePath: "/tmp/device-storage",
})
if err := device.Start(); err != nil {
t.Fatal(err)
}
defer device.Stop()
Features:
- Automatic building with
go build - Process lifecycle management (start, stop, graceful shutdown)
- Log capture and forwarding
- Port management
chiptool.go - chip-tool Wrapper
Wraps chip-tool commands for easy testing:
chipTool := framework.NewChipTool(t, framework.ChipToolConfig{
StorageDir: "/tmp/chip-tool-storage",
})
// Commission device
err := chipTool.PairOnNetwork(nodeID, pinCode)
// Send commands
err = chipTool.OnOffToggle(nodeID, endpointID)
// Read attributes
value, err := chipTool.ReadAttribute(nodeID, endpoint, "onoff", "on-off")
Features:
- Commissioning (onnetwork, code-based)
- OnOff cluster commands (on, off, toggle)
- Attribute reads
- Storage management
- Timeout handling
Test Pair (testpair.go)
Helper for creating commissioned device+controller pairs for e2e tests:
pair := NewTestPair(t, light.Factory)
defer pair.Close()
// Use pair.Controller and pair.Device
result, err := pair.Controller.SendCommand(...)
Running All Tests
# Run all non-interop tests
go test ./test/integration
# Run all tests including interop
go test -tags=interop ./test/integration
# Run with verbose output
go test -tags=interop ./test/integration -v
# Run a specific test
go test -tags=interop ./test/integration -run TestInterop_LightOnOffControl -v
Documentation
¶
Overview ¶
Package integration provides test infrastructure for Matter E2E tests.
Index ¶
- func DefaultControllerFactory(config matter.NodeConfig) (*controller.Controller, error)
- type ControllerFactory
- type DeviceFactory
- type TestController
- type TestDevice
- type TestPair
- func NewTestPair[D TestDevice](t *testing.T, deviceFactory DeviceFactory[D]) *TestPair[D, *controller.Controller]
- func NewTestPairWithConfig[D TestDevice](t *testing.T, deviceFactory DeviceFactory[D], config TestPairConfig) *TestPair[D, *controller.Controller]
- func NewTestPairWithController[D TestDevice, C TestController](t *testing.T, deviceFactory DeviceFactory[D], ...) *TestPair[D, C]
- type TestPairConfig
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DefaultControllerFactory ¶
func DefaultControllerFactory(config matter.NodeConfig) (*controller.Controller, error)
DefaultControllerFactory creates a standard controller.Controller.
Types ¶
type ControllerFactory ¶
type ControllerFactory[C TestController] func(config matter.NodeConfig) (C, error)
ControllerFactory creates a controller from a Matter node config. The default controller and specialized controllers provide their own factories.
type DeviceFactory ¶
type DeviceFactory[D TestDevice] func(config matter.NodeConfig) (D, error)
DeviceFactory creates a device from a Matter node config. Each device type (light, camera, etc.) provides its own factory.
type TestController ¶
type TestController interface {
// Start starts the controller.
Start(ctx context.Context) error
// Stop stops the controller.
Stop() error
// CommissionDevice commissions a device using PASE.
CommissionDevice(ctx context.Context, peerAddr transport.PeerAddress, passcode uint32) (*session.SecureContext, error)
}
TestController is the interface that controller types must implement for testing. Controller examples should implement this interface.
type TestDevice ¶
TestDevice is the interface that device types must implement for testing. Device examples (light.Device, camera.Device, etc.) should implement this.
type TestPair ¶
type TestPair[D TestDevice, C TestController] struct { // Device is the device under test. Device D // Controller is the Matter controller. Controller C // DeviceAddr is the device's transport address. DeviceAddr transport.PeerAddress // Session is the established secure session between controller and device. Session *session.SecureContext // Passcode used for commissioning. Passcode uint32 // contains filtered or unexported fields }
TestPair holds a commissioned device and controller pair for E2E testing. Generic over device type D and controller type C for type-safe access to device/controller-specific methods in tests.
Example usage:
pair := NewTestPair(t, light.Factory) defer pair.Close() pair.Device.IsOn() // Type-safe access to light-specific methods
func NewTestPair ¶
func NewTestPair[D TestDevice]( t *testing.T, deviceFactory DeviceFactory[D], ) *TestPair[D, *controller.Controller]
NewTestPair creates a device+controller pair with an established PASE session. This is the simple constructor that uses the standard controller.Controller.
Use this for most tests that don't need a specialized controller.
Example:
pair := NewTestPair(t, light.Factory)
defer pair.Close()
// Send command through controller
result, err := pair.Controller.SendCommand(...)
// Check device state
if !pair.Device.IsOn() { t.Error("expected light on") }
func NewTestPairWithConfig ¶
func NewTestPairWithConfig[D TestDevice]( t *testing.T, deviceFactory DeviceFactory[D], config TestPairConfig, ) *TestPair[D, *controller.Controller]
NewTestPairWithConfig creates a test pair with custom configuration. Uses the standard controller.Controller.
func NewTestPairWithController ¶
func NewTestPairWithController[D TestDevice, C TestController]( t *testing.T, deviceFactory DeviceFactory[D], controllerFactory ControllerFactory[C], config TestPairConfig, ) *TestPair[D, C]
NewTestPairWithController creates a test pair with a custom controller type. This is the advanced constructor for tests that need specialized controllers (e.g., camera controller with WebRTC support).
Example:
pair := NewTestPairWithController(t, camera.Factory, camera.ControllerFactory, config) defer pair.Close() // Use camera-specific controller methods stream, err := pair.Controller.StartStream(...)
func (*TestPair[D, C]) Close ¶
func (p *TestPair[D, C]) Close()
Close cleans up resources used by the pair. Should be called with defer after creating the pair.
func (*TestPair[D, C]) Context ¶
Context returns a context for operations on this pair. Uses a reasonable timeout for E2E operations.
func (*TestPair[D, C]) ContextWithTimeout ¶
ContextWithTimeout returns a context with custom timeout.
func (*TestPair[D, C]) LoggerFactory ¶
func (p *TestPair[D, C]) LoggerFactory() logging.LoggerFactory
LoggerFactory returns the logger factory used by this pair.
type TestPairConfig ¶
type TestPairConfig struct {
// DeviceConfig overrides for the device node.
// If nil, defaults are used.
DeviceVendorID uint16
DeviceProductID uint16
DeviceName string
DeviceDiscriminator uint16
DevicePasscode uint32
DevicePort int
// ControllerConfig overrides for the controller node.
ControllerVendorID uint16
ControllerProductID uint16
ControllerName string
ControllerDiscriminator uint16
ControllerPort int
// CommissioningTimeout is the timeout for the PASE handshake.
// Defaults to 30 seconds.
CommissioningTimeout time.Duration
// LoggerFactory for logging. If nil, uses DefaultLoggerFactory.
LoggerFactory logging.LoggerFactory
}
TestPairConfig configures the test pair creation.
func DefaultTestPairConfig ¶
func DefaultTestPairConfig() TestPairConfig
DefaultTestPairConfig returns default configuration for test pairs.
Source Files
Directories