framework

func (*ARPBuilder) Build ¶

func (b *ARPBuilder) Build() gopacket.SerializableLayer

func (*CLIManager) ExecuteCommand ¶

func (c *CLIManager) ExecuteCommand(command string) (string, error)

ExecuteCommand executes a single CLI command within the QEMU virtual machine via the serial console interface. The method ensures thread-safe execution, proper output collection, and reliable command completion detection using unique markers.

The execution process includes:

• VM readiness verification
• Command wrapping with start/end markers for reliable parsing
• Output buffering and cleanup of control characters
• Return code extraction and error handling

Parameters:

• command: The shell command to execute in the virtual machine

Returns:

• string: The cleaned command output (stdout/stderr combined)
• error: An error if the VM is not ready, command fails, or timeout occurs

Example:

output, err := cli.ExecuteCommand("ls -la /etc")
if err != nil {
    log.Fatalf("Command failed: %v", err)
}
fmt.Println("Directory listing:", output)

func (*CLIManager) ExecuteCommandWithTimeout ¶

func (c *CLIManager) ExecuteCommandWithTimeout(command string, timeout time.Duration) (string, error)

ExecuteCommandWithTimeout is like ExecuteCommand but with a custom timeout.

func (*CLIManager) ExecuteCommands ¶

func (c *CLIManager) ExecuteCommands(commands ...string) ([]string, error)

ExecuteCommands executes multiple CLI commands sequentially within the QEMU virtual machine. Each command is executed in order, and execution stops at the first command that returns an error.

This method is useful for executing a series of related commands where each command may depend on the success of previous ones, such as configuration setup or multi-step operations.

Parameters:

• commands: Variable number of shell commands to execute sequentially

Returns:

• []string: Slice of command outputs in execution order (may be partial if error occurs)
• error: An error from the first failed command, or nil if all commands succeed

Example:

outputs, err := cli.ExecuteCommands(
    "mkdir -p /tmp/test",
    "echo 'hello' > /tmp/test/file.txt",
    "cat /tmp/test/file.txt",
)
if err != nil {
    log.Fatalf("Command sequence failed: %v", err)
}

func (*CLIManager) ExecuteCommandsSeparately ¶

func (c *CLIManager) ExecuteCommandsSeparately(commands ...string) ([]string, []error)

ExecuteCommandsSeparately runs every command to completion regardless of individual failures, pairing each output with its own error. A diagnostics dump uses this so one failed probe (say, catting a log the crashed process never wrote) cannot hide the outputs of the rest.

func (*CLIManager) WithLog ¶

func (c *CLIManager) WithLog(log *zap.SugaredLogger) *CLIManager

WithLog creates a new CLIManager instance with a different logger while sharing the same underlying connection (inner state). This allows each test to have its own logging context while sharing the CLI manager connection.

Parameters:

• log: Logger to use for this CLI manager instance

Returns:

• *CLIManager: A new CLI manager instance with the specified logger

Example:

namedCLI := cli.WithLog(logger.Named("test1"))

func (*Dot1QBuilder) Build ¶

func (b *Dot1QBuilder) Build() gopacket.SerializableLayer

func (*EthernetBuilder) Build ¶

func (b *EthernetBuilder) Build() gopacket.SerializableLayer

func (*Framework) ForTest ¶

func (f *Framework) ForTest(t *testing.T) *TestFramework

ForTest creates a TestFramework instance bound to the provided *testing.T. This method should be called at the beginning of each test function to create a test-specific framework instance with automatic test name tracking.

Parameters:

• t: The *testing.T instance for the current test

Returns:

• *TestFramework: A test-bound framework instance

Example:

func TestMyFeature(t *testing.T) {
    fw := globalFramework.ForTest(t)
    fw.Run("SubTest", func(fw *TestFramework, t *testing.T) {
        // Test code here
    })
}

func (*Framework) Global ¶

func (f *Framework) Global() *TestFramework

Global returns the underlying TestFramework with testName="global" for global operations. This method should only be used in TestMain for framework lifecycle management (Start, Stop, StartYANET, etc.).

Returns:

• *TestFramework: The internal framework instance with testName="global"

Example:

func TestMain(m *testing.M) {
    fw, _ := New(config)
    globalFramework = fw
    gfw := fw.Global()
    gfw.Start()
    defer gfw.Stop()
    m.Run()
}

func (*GREBuilder) Build ¶

func (b *GREBuilder) Build() gopacket.SerializableLayer

func (GuestPaths) CLI ¶

func (p GuestPaths) CLI(name string) string

CLI returns the full path to a CLI binary by name.

func (*Harness) Pool ¶

func (m *Harness) Pool() *VMPool

Pool returns the underlying VM pool.

func (*Harness) Restore ¶

func (m *Harness) Restore(fw *TestFramework) error

Restore restores fw to a working YANET baseline without depending on the testing package. Lab tools use this method to get the same fast-path and fallback behavior as functional tests.

The fast path restores the "baseline" snapshot via RestoreClean, resets connections, and checks datapath readiness. The fallback restores the "preyanet" snapshot and starts YANET from scratch. Functional tests that pass no hooks get a fast path that differs from the older RestoreBooted contract (which used RestoreAndReconnect); the fallback path is unchanged.

func (*Harness) RestoreBooted ¶

func (m *Harness) RestoreBooted(t *testing.T, fw *TestFramework)

RestoreBooted restores fw to a working YANET state.

It tries the fast path (baseline snapshot with YANET already running) first, and falls back to the slow path (preyanet snapshot plus a fresh StartYANET) only when the baseline restore fails.

func (*Harness) Shutdown ¶

func (m *Harness) Shutdown() error

Shutdown stops every VM in the pool.

func (*Harness) WithBootedVM ¶

func (m *Harness) WithBootedVM(t *testing.T, fn func(fw *TestFramework))

WithBootedVM acquires a pooled VM, restores it to a working YANET baseline, runs fn, then returns the VM to the pool.

func (*ICMPBuilder) Build ¶

func (b *ICMPBuilder) Build() gopacket.SerializableLayer

func (*ICMPv6Builder) Build ¶

func (b *ICMPv6Builder) Build() gopacket.SerializableLayer

func (*ICMPv6EchoBuilder) Build ¶

func (b *ICMPv6EchoBuilder) Build() gopacket.SerializableLayer

func (*ICMPv6NeighborAdvertisementBuilder) Build ¶

func (b *ICMPv6NeighborAdvertisementBuilder) Build() gopacket.SerializableLayer

func (*ICMPv6NeighborSolicitationBuilder) Build ¶

func (b *ICMPv6NeighborSolicitationBuilder) Build() gopacket.SerializableLayer

func (*ICMPv6RouterAdvertisementBuilder) Build ¶

func (b *ICMPv6RouterAdvertisementBuilder) Build() gopacket.SerializableLayer

func (*ICMPv6RouterSolicitationBuilder) Build ¶

func (b *ICMPv6RouterSolicitationBuilder) Build() gopacket.SerializableLayer

func (*IPSecESPBuilder) Build ¶

func (b *IPSecESPBuilder) Build() gopacket.SerializableLayer

func (*IPv4Builder) Build ¶

func (b *IPv4Builder) Build() gopacket.SerializableLayer

func (*IPv6Builder) Build ¶

func (b *IPv6Builder) Build() gopacket.SerializableLayer

func (*IPv6ExtHdrDestOptBuilder) Build ¶

func (b *IPv6ExtHdrDestOptBuilder) Build() gopacket.SerializableLayer

Build constructs the IPv6 Destination Options extension header

func (*IPv6FragmentBuilder) Build ¶

func (b *IPv6FragmentBuilder) Build() gopacket.SerializableLayer

func (*MPLSBuilder) Build ¶

func (b *MPLSBuilder) Build() gopacket.SerializableLayer

Build constructs the MPLS layer

func (*PacketInfo) GetTransportProtocol ¶

func (info *PacketInfo) GetTransportProtocol() (layers.IPProtocol, bool)

GetTransportProtocol returns the transport layer protocol (TCP/UDP) from the packet. For tunneled packets, it returns the protocol from the inner packet. Returns the IPProtocol value and a boolean indicating if a valid transport protocol was found.

func (*PacketInfo) String ¶

func (info *PacketInfo) String() string

String returns a human-readable string representation of the packet information, including all relevant protocol details, addressing information, and tunnel status. This method is useful for debugging, logging, and test result presentation.

The string representation includes:

• Source and destination IP addresses
• IP version information (IPv4/IPv6) with protocol details
• Transport layer port information (if available)
• Tunnel information and inner packet details (if tunneled)

Returns:

• string: Formatted packet information suitable for display and logging

Example output:

"Packet: 192.168.1.1 -> 10.0.0.1 (IPv4, proto=4), tunnel=ip4in4, inner=172.16.1.1->172.16.1.2"

func (*PacketParser) ParsePacket ¶

func (p *PacketParser) ParsePacket(data []byte) (*PacketInfo, error)

ParsePacket parses raw packet data and extracts comprehensive protocol information into a structured PacketInfo object. The method handles various networking protocols and automatically detects tunneled/encapsulated packets.

The parsing process includes:

• Ethernet frame validation and padding to minimum size
• Multi-layer protocol parsing (Ethernet, IP, Transport)
• Tunnel detection and inner packet analysis
• Payload extraction and error handling

Parameters:

• data: Raw packet bytes to parse (minimum 60 bytes after padding)

Returns:

• *PacketInfo: Structured packet information with all parsed layers
• error: An error if packet parsing fails or data is malformed

Example:

parser := NewPacketParser()
info, err := parser.ParsePacket(rawPacketData)
if err != nil {
    log.Fatalf("Packet parsing failed: %v", err)
}
fmt.Printf("Parsed packet: %s", info.String())

func (*PacketParser) VerifyDecapsulation ¶

func (p *PacketParser) VerifyDecapsulation(originalPacket, processedPacket *PacketInfo) error

VerifyDecapsulation validates that a tunneled packet has been properly decapsulated by comparing the processed packet against the original inner packet. This verification method is essential for testing tunnel processing functionality.

The verification process includes:

• Confirming the original packet was tunneled
• Validating inner packet information exists
• Comparing IP version consistency (IPv4/IPv6)
• Verifying source and destination IP address preservation
• Ensuring tunnel headers have been properly removed

Parameters:

• originalPacket: The original tunneled packet before processing
• processedPacket: The packet after decapsulation processing

Returns:

• error: An error if decapsulation verification fails or packets don't match

Example:

err := parser.VerifyDecapsulation(tunneled, decapsulated)
if err != nil {
    log.Fatalf("Decapsulation verification failed: %v", err)
}

func (*PacketParser) VerifyNAT64Translation ¶

func (p *PacketParser) VerifyNAT64Translation(originalPacket, translatedPacket *PacketInfo, nat64Prefix string) error

VerifyNAT64Translation validates NAT64 protocol translation between IPv4 and IPv6 packets, ensuring proper address mapping and prefix usage. This method is crucial for testing NAT64 functionality in dual-stack network environments.

The verification process includes:

• IPv4-to-IPv6 translation validation with prefix checking
• IPv6-to-IPv4 translation validation with embedded address extraction
• NAT64 prefix compliance verification (typically 64:ff9b::/96)
• Embedded IPv4 address consistency checking

Supported translation directions:

• IPv4 → IPv6: Verifies IPv6 address is in NAT64 prefix with embedded IPv4
• IPv6 → IPv4: Verifies original IPv6 was in prefix and extracts embedded IPv4

Parameters:

• originalPacket: The packet before NAT64 translation
• translatedPacket: The packet after NAT64 translation
• nat64Prefix: NAT64 prefix in CIDR notation (e.g., "64:ff9b::/96")

Returns:

• error: An error if NAT64 translation verification fails or addresses don't match

Example:

err := parser.VerifyNAT64Translation(ipv4Pkt, ipv6Pkt, "64:ff9b::/96")
if err != nil {
    log.Fatalf("NAT64 translation verification failed: %v", err)
}

func (*QEMUManager) AbortSerial ¶

func (q *QEMUManager) AbortSerial()

AbortSerial stops the serial reader and closes the serial connection, causing in-flight ExecuteCommand calls to fail immediately. The caller must reconnect (via reset/up) before issuing further guest commands.

func (*QEMUManager) AttachSerial ¶

func (q *QEMUManager) AttachSerial() (net.Conn, func() error, error)

AttachSerial gives a caller exclusive access to the serial console.

The returned release function restores the framework's serial reader and waits for a fresh prompt before another framed command can run.

func (*QEMUManager) EnableSSHForward ¶

func (q *QEMUManager) EnableSSHForward()

EnableSSHForward configures a loopback SSH forward for this VM.

func (*QEMUManager) ForceStop ¶

func (q *QEMUManager) ForceStop()

ForceStop makes Stop terminate this VM even when the test keep-alive mode is set.

func (*QEMUManager) GetStdin ¶

func (q *QEMUManager) GetStdin() io.WriteCloser

GetStdin returns the stdin pipe for the QEMU process

func (*QEMUManager) IsVMReady ¶

func (q *QEMUManager) IsVMReady() bool

IsVMReady returns the current readiness state of the virtual machine in a thread-safe manner. This method can be called from multiple goroutines without synchronization concerns.

VM readiness indicates that the virtual machine has completed its boot process and is ready to accept and execute commands through the serial console.

Returns:

• bool: True if the VM is ready for command execution, false otherwise

Example:

if manager.IsVMReady() {
    // Safe to execute commands
    output, err := cli.ExecuteCommand("ls -la")
}

func (*QEMUManager) ReconnectSerial ¶

func (q *QEMUManager) ReconnectSerial() error

ReconnectSerial closes the current serial connection and opens a new one. The caller is responsible for resetting readySignal and launching a new readSerial goroutine after this returns.

func (*QEMUManager) RestartSerial ¶

func (q *QEMUManager) RestartSerial() error

RestartSerial reconnects the serial console and restarts the reader goroutine after an AbortSerial call. Use this to restore command execution capability after an abort.

func (*QEMUManager) RestoreBooted ¶

func (q *QEMUManager) RestoreBooted() error

RestoreBooted restores the VM to the "booted" snapshot without going through the full framework-level RestoreAndReconnect. It handles the monitor loadvm, serial reconnect, and ready wait at the QEMUManager level.

Callers are responsible for unmounting 9P before calling and remounting after.

func (*QEMUManager) RestoreSnapshot ¶

func (q *QEMUManager) RestoreSnapshot(name string) error

RestoreSnapshot restores the VM to a previously saved snapshot. After restore, the serial console connection is broken (the guest-side state reverts) and must be re-established via ReconnectSerial.

The monitor connection itself survives because it is external to the guest state.

func (*QEMUManager) SSHPort ¶

func (q *QEMUManager) SSHPort() int

SSHPort returns the loopback port forwarded to the guest SSH server.

func (*QEMUManager) SaveBootedOverlay ¶

func (q *QEMUManager) SaveBootedOverlay() (string, error)

SaveBootedOverlay saves the "booted" snapshot to the VM's current overlay and returns the overlay file path. The caller can copy this path to a cache location and use it as TemplateOverlay for other VMs.

func (*QEMUManager) SaveSnapshot ¶

func (q *QEMUManager) SaveSnapshot(name string) error

SaveSnapshot creates a named QEMU VM snapshot via the monitor. The snapshot captures the full VM state (CPU, RAM, devices) and can be restored later with RestoreSnapshot. This is the key primitive for per-test state isolation.

func (*QEMUManager) SaveSnapshotOverlay ¶

func (q *QEMUManager) SaveSnapshotOverlay(name string) (string, error)

SaveSnapshotOverlay saves the named snapshot to the VM's current overlay and returns the overlay file path. The caller can copy this path to a cache location and use it as TemplateOverlay for other VMs.

The 9P shares must be unmounted before calling (savevm blocks when VirtFS mounts are active).

func (*QEMUManager) SendMonitorCommand ¶

func (q *QEMUManager) SendMonitorCommand(cmd string) (string, error)

SendMonitorCommand sends a command to the QEMU monitor (HMP) and returns the response. The monitor socket must already be connected via Start(). Commands are terminated with a newline; the method waits for the next "(qemu) " prompt to determine when the response is complete.

func (*QEMUManager) Start ¶

func (q *QEMUManager) Start() (bool, error)

Start launches a QEMU virtual machine. When TemplateOverlay is set the overlay is copied from it and QEMU starts with -loadvm for the requested TemplateSnapshotName, skipping the slow cold boot path.

Returns (true, nil) when booted from snapshot, (false, nil) when doing a full cold boot.

func (*QEMUManager) Stop ¶

func (q *QEMUManager) Stop() error

Stop performs graceful termination of the QEMU virtual machine and comprehensive cleanup of all associated resources. This method ensures proper resource deallocation and prevents resource leaks in testing environments.

The cleanup process includes:

• Graceful closure of monitor and serial console connections
• QEMU process termination with proper signal handling
• Working directory and temporary file cleanup
• Unix socket file removal from filesystem
• Error collection and reporting for failed cleanup operations

Multiple cleanup errors are collected and returned as a combined error to provide comprehensive information about any cleanup failures.

Returns:

• error: A combined error if any cleanup operations fail, or nil if successful

Example:

if err := manager.Stop(); err != nil {
    log.Errorf("VM cleanup encountered errors: %v", err)
}

func (*QEMUManager) WaitForReady ¶

func (q *QEMUManager) WaitForReady(timeout time.Duration) error

WaitForReady blocks until the virtual machine becomes ready for command execution or the specified timeout expires. This method provides synchronous waiting for VM readiness with proper timeout handling.

The method first checks if the VM is already ready to avoid unnecessary waiting. If not ready, it waits for the readiness signal from the background monitoring goroutine.

Parameters:

• timeout: Maximum time to wait for VM readiness

Returns:

• error: An error if the timeout expires before VM becomes ready, or nil if ready

Example:

if err := manager.WaitForReady(60 * time.Second); err != nil {
    log.Fatalf("VM failed to become ready: %v", err)
}

func (*RawBuilder) Build ¶

func (b *RawBuilder) Build() gopacket.SerializableLayer

func (*SocketClient) Close ¶

func (sc *SocketClient) Close() error

Close gracefully terminates the socket connection and releases associated network resources. This method should be called when the socket client is no longer needed to prevent resource leaks.

The method safely handles cases where no connection is established and provides proper error reporting for connection closure failures.

Returns:

• error: An error if connection closure fails, or nil if successful or no connection exists

Example:

defer func() {
    if err := client.Close(); err != nil {
        log.Errorf("Failed to close socket connection: %v", err)
    }
}()

func (*SocketClient) Connect ¶

func (sc *SocketClient) Connect() error

Connect establishes a network connection to the QEMU socket interface with automatic retry logic and proper error handling. The method supports both TCP and Unix socket connections based on the client configuration.

The connection process includes:

• Automatic detection of connection type (TCP vs Unix socket)
• Retry logic with exponential backoff for handling timing issues
• Proper error reporting and logging for debugging
• Connection state management to prevent duplicate connections

The method attempts connection up to 10 times with 2-second intervals to accommodate QEMU startup timing and network interface availability.

Returns:

• error: An error if connection cannot be established after all retry attempts

Example:

if err := client.Connect(); err != nil {
    log.Fatalf("Failed to connect to QEMU socket: %v", err)
}

func (*SocketClient) GetSocketPort ¶

func (sc *SocketClient) GetSocketPort() int

GetSocketPort returns the TCP port number configured for this socket client. This method is useful for debugging and logging purposes, particularly when working with multiple socket clients on different ports.

Returns:

• int: TCP port number, or 0 if the client is configured for Unix sockets

Example:

port := client.GetSocketPort()
if port > 0 {
    log.Infof("Client configured for TCP port %d", port)
} else {
    log.Info("Client configured for Unix socket")
}

func (*SocketClient) ReceiveAllPackets ¶

func (sc *SocketClient) ReceiveAllPackets(timeout time.Duration, dumpPath string) ([][]byte, error)

ReceiveAllPackets receives all packets available on the socket within the timeout.

func (*SocketClient) ReceiveAllPacketsUnfiltered ¶

func (sc *SocketClient) ReceiveAllPacketsUnfiltered(timeout time.Duration, dumpPath string) ([][]byte, error)

ReceiveAllPacketsUnfiltered receives every packet observed on the socket during a fixed window of timeout, without the destination-MAC filtering ReceiveAllPackets applies.

Solicited responses to injected traffic always carry the host's simulated MAC as destination, which is what that filter matches. Traffic the dataplane emits on its own initiative often addresses a multicast destination instead and would otherwise be silently dropped, so callers that need to observe unsolicited traffic must use this method.

Unlike ReceiveAllPackets, which stops as soon as the link falls idle for timeout, this method always reads for the entire window: a source that emits periodic unsolicited traffic more often than timeout never falls idle, so an idle-based cutoff would never return.

func (*SocketClient) ReceivePacket ¶

func (sc *SocketClient) ReceivePacket(timeout time.Duration, dumpPath string) ([]byte, error)

ReceivePacket captures a network packet from the QEMU socket connection with MAC address filtering and timeout handling. The method implements the QEMU socket protocol by reading length-prefixed packets and filtering based on destination MAC address for test isolation.

The reception process includes:

• Connection state validation and timeout configuration
• Length prefix parsing from network byte order
• Packet size validation to prevent buffer overflows
• Complete packet data reception
• MAC address-based filtering for test packet isolation
• Automatic packet parsing and validation
• Optional dumping to file if dumpFilePaths is provided

The method continuously reads packets until it finds one with the correct destination MAC address matching the test framework's source MAC, ensuring proper packet isolation in multi-test scenarios.

Parameters:

• timeout: Maximum time to wait for packet reception
• dumpPath: Path to dump file for recording socket data (empty string to skip dumping)

Returns:

• []byte: Raw packet data with correct destination MAC address
• error: An error if connection fails, timeout occurs, or no matching packet is received

Example:

packet, err := client.ReceivePacket(5 * time.Second, "/path/to/dump.file")
if err != nil {
    log.Fatalf("Packet reception failed: %v", err)
}
fmt.Printf("Received packet: %x", packet)

func (*SocketClient) ResetConnection ¶

func (sc *SocketClient) ResetConnection() error

ResetConnection closes the existing connection and creates a new one. This ensures a clean stream with no buffered data from previous operations. This method is used for test isolation to prevent packet leakage between tests.

The method:

• Closes any existing connection (discarding buffered data)
• Creates a new connection to the same socket
• Returns an error if reconnection fails

Returns:

• error: An error if reconnection fails, or nil if successful

Example:

if err := client.ResetConnection(); err != nil {
    log.Fatalf("Failed to reset connection: %v", err)
}

func (*SocketClient) SendAndReceivePacket ¶

func (sc *SocketClient) SendAndReceivePacket(budget *ReplyBudget, packet []byte, dumpPath string) ([]byte, error)

SendAndReceivePacket transmits packet and waits for a single reply, returning the raw reply bytes.

The wait is not retried on timeout: a late reply is far more likely than a lost one under a starved CI runner, and resending risks a duplicate packet through stateful modules. budget must be shared by every call in one subtest — see ReplyBudget for what that buys when replies are missing by construction. A missing reply returns a nil slice and a nil error, not an error, and surfaces later as a packet-count mismatch.

Parameters:

• budget: Per-subtest pool debited only when a read times out
• packet: Raw packet bytes to transmit through the socket
• dumpPath: Path to dump file for recording socket data (empty string to skip dumping)

Returns:

• []byte: Raw reply bytes, or nil if no reply arrived
• error: An error if the packet could not be sent, or the read failed for a reason other than a timeout

func (*SocketClient) SendPacket ¶

func (sc *SocketClient) SendPacket(packet []byte, dumpPath string) error

SendPacket transmits a raw network packet through the QEMU socket connection with proper length prefixing and timeout handling. The method implements the QEMU socket protocol by prefixing each packet with its length in network byte order.

The transmission process includes:

• Connection state validation
• Write timeout configuration for reliable transmission
• Length prefix encoding in big-endian format
• Complete packet data transmission
• Comprehensive error handling and logging
• Optional dumping to file if dumpFilePaths is provided

The packet format follows QEMU socket networking protocol:

[4-byte length][packet data]

Parameters:

• packet: Raw packet bytes to transmit through the socket
• dumpPath: Path to dump file for recording socket data (empty string to skip dumping)

Returns:

• error: An error if the connection is not established, timeout occurs, or transmission fails

Example:

packetData := []byte{0x52, 0x54, 0x00, 0x6b, 0xff, 0xa1, ...} // Ethernet frame
if err := client.SendPacket(packetData, "/path/to/dump.file"); err != nil {
    log.Fatalf("Packet transmission failed: %v", err)
}

func (*SocketClient) SendPackets ¶

func (sc *SocketClient) SendPackets(packets [][]byte, dumpPath string) error

func (*SocketClient) WithLog ¶

func (sc *SocketClient) WithLog(log *zap.SugaredLogger) *SocketClient

WithLog creates a new SocketClient instance with a different logger while sharing the same underlying connection (inner state). This allows each test to have its own logging context while sharing the socket connection.

Parameters:

• log: Logger to use for this client instance

Returns:

• *SocketClient: A new socket client instance with the specified logger

Example:

namedClient := client.WithLog(logger.Named("test1"))

func (*TCPBuilder) Build ¶

func (b *TCPBuilder) Build() gopacket.SerializableLayer

func (*TestFramework) AbortGuestSerial ¶

func (f *TestFramework) AbortGuestSerial()

AbortGuestSerial closes the guest serial connection so in-flight ExecuteCommand calls fail. The caller must reconnect before issuing further guest commands.

func (*TestFramework) AdoptRunningConfig ¶

func (f *TestFramework) AdoptRunningConfig(dataplaneConfig string, controlplaneConfig string)

AdoptRunningConfig records the configuration to restart the guest with.

It starts nothing. A VM restored from a baseline snapshot boots with YANET already running, so the framework driving it never called StartYANET and therefore holds no configuration for RestartYANET to restart from. Call this once the caller knows what configuration the running guest was baked with, so a later in-place restart has something to fall back to.

func (*TestFramework) AttachSerial ¶

func (f *TestFramework) AttachSerial() (net.Conn, func() error, error)

AttachSerial gives a caller exclusive access to the guest serial console.

func (*TestFramework) CommonConfigCommands ¶

func (f *TestFramework) CommonConfigCommands() []string

CommonConfigCommands returns the shell commands that configure the baseline YANET state (kni0, forwarding, route FIB, pipelines, devices). Paths are resolved from f.Paths so the commands work with both 9P and local tmpfs layouts.

func (*TestFramework) CreateConfigFile ¶

func (f *TestFramework) CreateConfigFile(name string, config string) error

func (*TestFramework) CreateForwardConfig ¶

func (f *TestFramework) CreateForwardConfig(config string) error

CreateForwardConfig writes forward.yaml to the path referenced by f.Paths.ForwardYAML. In 9P mode this writes to the host filesystem; in local mode it writes via serial console to the guest tmpfs.

func (*TestFramework) ExecuteCommand ¶

func (f *TestFramework) ExecuteCommand(command string) (string, error)

ExecuteCommand executes a single CLI command within the QEMU virtual machine via the serial console interface. This is a proxy method that delegates to the underlying CLI manager.

For test-specific frameworks (created via ForTest), commands are logged with the test's unique log ID for easy debugging.

Parameters:

• command: The shell command to execute in the virtual machine

Returns:

• string: The cleaned command output (stdout/stderr combined)
• error: An error if the VM is not ready, command fails, or timeout occurs

Example:

fw := globalFramework.ForTest(t)
fw.Run("ExecuteCommand", func(fw *TestFramework, t *testing.T) {
    output, err := fw.ExecuteCommand("ls -la /etc")
    require.NoError(t, err)
    t.Logf("Output: %s", output)
})

func (*TestFramework) ExecuteCommandWithTimeout ¶

func (f *TestFramework) ExecuteCommandWithTimeout(command string, timeout time.Duration) (string, error)

ExecuteCommandWithTimeout executes a single CLI command with a custom timeout. Use this for operations that may take longer than the default 30s, such as copying large binaries on slow emulated VMs.

func (*TestFramework) ExecuteCommands ¶

func (f *TestFramework) ExecuteCommands(commands ...string) ([]string, error)

ExecuteCommands executes multiple CLI commands sequentially within the QEMU virtual machine. This is a proxy method that delegates to the underlying CLI manager.

Each command is executed in order, and execution stops at the first command that returns an error.

Parameters:

• commands: Variable number of shell commands to execute sequentially

Returns:

• []string: Slice of command outputs in execution order (may be partial if error occurs)
• error: An error from the first failed command, or nil if all commands succeed

Example:

fw := globalFramework.ForTest(t)
fw.Run("ExecuteCommands", func(fw *TestFramework, t *testing.T) {
    outputs, err := fw.ExecuteCommands(
        "mkdir -p /tmp/test",
        "echo 'hello' > /tmp/test/file.txt",
        "cat /tmp/test/file.txt",
    )
    require.NoError(t, err)
    t.Logf("Outputs: %v", outputs)
})

func (*TestFramework) ExecuteCommandsSeparately ¶

func (f *TestFramework) ExecuteCommandsSeparately(commands ...string) ([]string, []error)

ExecuteCommandsSeparately runs every command to completion regardless of individual failures, pairing each output with its own error.

func (*TestFramework) ExportCurrentOverlay ¶

func (f *TestFramework) ExportCurrentOverlay(dst string) error

ExportCurrentOverlay copies the VM's current qcow2 overlay to dst.

A successful export leaves the VM paused. Callers must stop it or explicitly resume it before further use. This is used to cache prepared template overlays and start future pool VMs from the same snapshot source.

func (*TestFramework) ForTest ¶

func (f *TestFramework) ForTest(t *testing.T) *TestFramework

ForTest binds an already constructed framework instance to a specific test. This is used by pooled VMs, where tests acquire a shared base framework from VMPool and then need a test-scoped copy with the proper logger and *testing.T.

func (*TestFramework) GetSocketClient ¶

func (f *TestFramework) GetSocketClient(ifaceIndex int) (*SocketClient, error)

GetSocketClient retrieves or creates a socket client for the specified network interface. The method implements caching to reuse existing connections and ensures thread-safe access to the socket client pool.

For test-specific frameworks (created via ForTest), the socket client is returned with a named logger using the test's log ID.

The method handles:

• Interface index validation against available QEMU socket paths
• Thread-safe access to the socket client cache
• Automatic socket client creation for new interfaces
• Client caching for performance optimization
• Logger customization for test-specific contexts

Parameters:

• ifaceIndex: Zero-based index of the network interface (must be < len(SocketPaths))

Returns:

• *SocketClient: Socket client for the specified interface
• error: An error if the interface index is invalid or client creation fails

Example:

client, err := fw.GetSocketClient(0)
if err != nil {
    log.Fatalf("Failed to get socket client: %v", err)
}
defer client.Close()

func (*TestFramework) GetSocketPaths ¶

func (f *TestFramework) GetSocketPaths() []string

func (*TestFramework) Mount9P ¶

func (f *TestFramework) Mount9P() error

Mount9P remounts all 9P shares inside the guest VM. Uses mount -a for speed, then verifies each mount point is present.

func (*TestFramework) PrepareLocalStorage ¶

func (f *TestFramework) PrepareLocalStorage() error

PrepareLocalStorage copies all YANET binaries, CLI tools, configs and scripts from 9P mounts to /tmp/yanet/ inside the guest. After this call, YANET can be started from local tmpfs paths so that no process holds open fids on 9P mounts, making savevm/loadvm work cleanly.

This also switches f.Paths to LocalGuestPaths().

func (*TestFramework) ResetConnections ¶

func (f *TestFramework) ResetConnections()

ResetConnections closes and reconnects all socket clients. This ensures a clean state after a snapshot restore, preventing stale connections from causing false heartbeat failures. Unlike draining, this approach guarantees a completely clean stream by discarding any buffered data with the old connection.

Must be called after loadvm and before any packet operations (WaitForDatapathReady, SendPacketAndCapture, etc.) because loadvm restores QEMU's internal stream-netdev state but the host-side UNIX socket connections are stale — Connect() short-circuits on the dead net.Conn and never reconnects.

Errors during reset are logged but do not cause the operation to fail.

func (*TestFramework) RestartGuestSerial ¶

func (f *TestFramework) RestartGuestSerial() error

RestartGuestSerial reconnects the serial console and restarts the reader goroutine after an AbortGuestSerial call.

func (*TestFramework) RestartYANET ¶

func (f *TestFramework) RestartYANET() error

func (*TestFramework) RestoreAndReconnect ¶

func (f *TestFramework) RestoreAndReconnect(snapshot string) error

RestoreAndReconnect reverts the VM to a previously saved snapshot and re-establishes the serial console and socket connections that break when the guest state is rolled back.

Call sequence after restore:

1. Unmount 9P shares
2. loadvm via QEMU monitor (monitor socket survives)
3. Reconnect serial console
4. Wait for shell prompts
5. Mount 9P shares
6. Reset socket connections (close stale connections, reconnect)
7. Wait for dataplane ready (ICMP heartbeat)

Socket connections MUST be reset before the heartbeat because loadvm restores QEMU's internal stream-netdev state but the host-side UNIX socket connections are stale. Without reset, Connect() short-circuits on the dead net.Conn and heartbeat fails silently.

func (*TestFramework) RestoreBooted ¶

func (f *TestFramework) RestoreBooted() error

RestoreBooted restores the VM to the "booted" snapshot and re-establishes all connections. This is the primary per-test isolation primitive.

Unlike RestoreAndReconnect("baseline"), RestoreBooted does not depend on a baseline snapshot being created at test startup. It only requires that the VM pool was started from a pre-prepared booted template overlay.

func (*TestFramework) RestoreClean ¶

func (f *TestFramework) RestoreClean(snapshot string) error

RestoreClean reverts the VM to a previously saved snapshot and re-establishes serial console and 9P mounts WITHOUT running the dataplane heartbeat check. Use this for snapshots where YANET is not yet running (e.g. "preyanet") -- StartYANET will be called separately after restore.

func (*TestFramework) Run ¶

func (f *TestFramework) Run(name string, fn func(fw *TestFramework, t *testing.T)) bool

Run executes a subtest with the given name and function. This method wraps t.Run() and automatically creates a new TestFramework instance with the correct test name. This ensures that all framework operations within the subtest are properly tracked and logged.

The callback function receives two parameters:

• fw: A new *TestFramework instance with the correct test name set
• t: The *testing.T instance for the subtest

This design separates framework operations (via fw) from test assertions (via t), making the code more explicit and preventing accidental use of the wrong test context.

Parameters:

• name: The name of the subtest
• fn: The test function that receives fw and t

Returns:

• bool: True if the test passed, false otherwise (same as t.Run)

Example:

func TestMyFeature(t *testing.T) {
    fw := globalFramework.ForTest(t)

    fw.Run("BasicTest", func(fw *TestFramework, t *testing.T) {
        input, output, err := fw.SendPacketAndParse(0, 0, packet, timeout)
        require.NoError(t, err)
    })

    fw.Run("AdvancedTest", func(fw *TestFramework, t *testing.T) {
        _, err := fw.ExecuteCommand("some command")
        require.NoError(t, err)
    })
}

func (*TestFramework) RunWith ¶

func (f *TestFramework) RunWith(snapshot string, name string, fn func(fw *TestFramework, t *testing.T)) bool

RunWith is like Run but restores the named VM snapshot before executing the test function. This gives each subtest a guaranteed clean VM state matching the configuration at snapshot time.

Use Run() (without snapshot restore) for subtests that intentionally build on the state left by previous subtests. Use RunWith() when each subtest needs full isolation.

func (*TestFramework) SSHPort ¶

func (f *TestFramework) SSHPort() int

SSHPort returns the loopback port forwarded to the guest SSH server.

func (*TestFramework) SaveSnapshot ¶

func (f *TestFramework) SaveSnapshot(name string) error

SaveSnapshot saves a named VM snapshot that captures the full machine state (CPU, RAM, devices). Subsequent calls to RestoreAndReconnect can revert the VM to this point. This is typically called from TestMain after YANET is configured to create a "baseline" snapshot.

The method unmounts all 9P shares before savevm (to remove QEMU migration blockers) and remounts them afterward. This only works cleanly when PrepareLocalStorage() was called first so that no process holds open fids on 9P mounts.

func (*TestFramework) SaveSnapshotKeepUnmounted ¶

func (f *TestFramework) SaveSnapshotKeepUnmounted(name string) error

SaveSnapshotKeepUnmounted saves a snapshot like SaveSnapshot but does NOT remount 9P shares afterward. Use this for baseline snapshots in pool mode: since RestoreAndReconnect will loadvm immediately, the intermediate remount would just be unmounted again before loadvm, wasting ~4s per test.

func (*TestFramework) SendPacketAndCapture ¶

func (f *TestFramework) SendPacketAndCapture(inputIfaceIndex int, outputIfaceIndex int, packet []byte, timeout time.Duration) ([]byte, error)

SendPacketAndCapture sends a network packet through the specified input interface and captures any response from the output interface without performing packet verification or parsing. This is a low-level method for raw packet testing.

The method handles:

• Socket client retrieval and connection management
• Packet transmission through the input interface
• Response capture from the output interface with timeout
• Automatic socket connection establishment
• Optional socket data dumping when debug mode is enabled

Parameters:

• inputIfaceIndex: Index of the network interface to send the packet through
• outputIfaceIndex: Index of the network interface to capture response from
• packet: Raw packet data to transmit
• timeout: Maximum time to wait for response capture

Returns:

• []byte: Raw response packet data, or nil if no response received
• error: An error if packet transmission fails or interfaces are unavailable

Example:

fw := globalFramework.ForTest(t)
fw.Run("SendPacket", func(fw *TestFramework, t *testing.T) {
    response, err := fw.SendPacketAndCapture(0, 1, packetData, 5*time.Second)
    require.NoError(t, err)
})

func (*TestFramework) SendPacketAndCaptureAll ¶

func (f *TestFramework) SendPacketAndCaptureAll(inputIfaceIndex int, outputIfaceIndex int, packet []byte, timeout time.Duration) ([][]byte, error)

SendPacketAndCaptureAll sends a network packet and captures all response packets.

func (*TestFramework) SendPacketAndCaptureAllUnfiltered ¶

func (f *TestFramework) SendPacketAndCaptureAllUnfiltered(inputIfaceIndex int, outputIfaceIndex int, packet []byte, timeout time.Duration) ([][]byte, error)

SendPacketAndCaptureAllUnfiltered captures every packet observed on the selected egress during timeout.

func (*TestFramework) SendPacketAndParse ¶

func (f *TestFramework) SendPacketAndParse(inputIfaceIndex int, outputIfaceIndex int, packet []byte, timeout time.Duration) (*PacketInfo, *PacketInfo, error)

SendPacketAndParse sends a network packet, captures the response, and parses both the input and output packets into structured PacketInfo objects. This high-level method provides comprehensive packet analysis for detailed testing scenarios.

The method performs:

• Input packet parsing and validation
• Packet transmission through the specified interfaces
• Response capture with timeout handling
• Output packet parsing and analysis
• Detailed logging of packet flow for debugging
• Optional socket data dumping when debug mode is enabled

Parameters:

• inputIfaceIndex: Index of the network interface to send the packet through
• outputIfaceIndex: Index of the network interface to capture response from
• packet: Raw packet data to transmit
• timeout: Maximum time to wait for response capture

Returns:

• *PacketInfo: Parsed information about the input packet
• *PacketInfo: Parsed information about the output packet (nil if no response)
• error: An error if packet processing, transmission, or parsing fails

Example:

fw := globalFramework.ForTest(t)
fw.Run("ParsePacket", func(fw *TestFramework, t *testing.T) {
    input, output, err := fw.SendPacketAndParse(0, 1, packetData, 5*time.Second)
    require.NoError(t, err)
    t.Logf("Sent: %s, Received: %s", input.String(), output.String())
})

func (*TestFramework) SendPacketAndParseAll ¶

func (f *TestFramework) SendPacketAndParseAll(inputIfaceIndex int, outputIfaceIndex int, packet []byte, timeout time.Duration) ([]*PacketInfo, error)

SendPacketAndParseAll sends a network packet and captures ALL response packets.

func (*TestFramework) SendPacketsAndParseAll ¶

func (f *TestFramework) SendPacketsAndParseAll(inputIfaceIndex int, outputIfaceIndex int, packets [][]byte, timeout time.Duration) ([]*PacketInfo, error)

func (*TestFramework) Start ¶

func (f *TestFramework) Start() (bool, error)

Start initializes and launches the complete test environment, including the QEMU virtual machine with configured networking. This method must be called before executing any tests or VM operations.

The startup process includes:

• QEMU virtual machine launch with socket networking
• Network interface initialization
• VM readiness verification

Returns:

• error: An error if VM startup fails or networking cannot be established

Example:

if err := framework.Start(); err != nil {
    log.Fatalf("Failed to start test environment: %v", err)
}

func (*TestFramework) StartLogTailers ¶

func (f *TestFramework) StartLogTailers() error

StartLogTailers starts background processes that tail YANET log files from local tmpfs to the 9P-mounted /mnt/logs/ directory, making logs visible on the host in real time. Must be called after YANET is running and 9P mounts are available.

func (*TestFramework) StartYANET ¶

func (f *TestFramework) StartYANET(dataplaneConfig string, controlplaneConfig string) error

StartYANET initializes and launches the complete YANET network processing stack within the virtual machine environment. This comprehensive method handles all aspects of YANET deployment including configuration, kernel module loading, network interface binding, and service startup.

The startup process includes:

• Configuration file creation and validation
• YANET binary availability verification
• Required kernel module loading (vfio-pci)
• Network interface binding to DPDK drivers
• YANET dataplane service startup with background execution
• YANET controlplane service startup and readiness verification
• Service health checks and log monitoring

Parameters:

• dataplaneConfig: YAML configuration content for the YANET dataplane service
• controlplaneConfig: YAML configuration content for the YANET controlplane service

Returns:

• error: An error if any step of the YANET startup process fails

Example:

dataplaneYAML := `
interfaces:
  - name: "eth0"
    pci: "01:00.0"
`
controlplaneYAML := `
modules:
  - name: "forward"
`
if err := fw.StartYANET(dataplaneYAML, controlplaneYAML); err != nil {
    log.Fatalf("YANET startup failed: %v", err)
}

func (*TestFramework) Stop ¶

func (f *TestFramework) Stop() error

Stop performs cleanup of the test environment, closing socket clients and stopping the QEMU virtual machine.

Multiple cleanup errors are collected and returned as a combined error.

func (*TestFramework) Unmount9P ¶

func (f *TestFramework) Unmount9P() error

Unmount9P unmounts all 9P shares inside the guest VM. This removes the QEMU migration blockers so that savevm/loadvm can proceed. When PrepareLocalStorage() has been called first, no process holds open fids on 9P mounts and plain umount works. Log tailer processes (tail -f >> /mnt/logs/...) are killed first because they hold open fids on /mnt/logs via write-append.

func (*TestFramework) WaitForDatapathReady ¶

func (f *TestFramework) WaitForDatapathReady(timeout time.Duration) error

WaitForDatapathReady sends ICMP heartbeat packets until the dataplane responds, confirming DPDK virtio-user reconnect after a snapshot restore. No operstate check — on macOS TCG and Linux KVM, kni0 operstate stays DOWN even when DPDK is actively forwarding. Only an end-to-end packet test works.

func (*TestFramework) WaitForReady ¶

func (f *TestFramework) WaitForReady(timeout time.Duration) error

WaitForReady blocks until the QEMU virtual machine becomes ready for command execution or the specified timeout expires. This is a proxy method for QEMU.WaitForReady.

Parameters:

• timeout: Maximum time to wait for VM readiness

Returns:

• error: An error if the timeout expires before VM becomes ready, or nil if ready

Example:

if err := fw.WaitForReady(60 * time.Second); err != nil {
    log.Fatalf("VM failed to become ready: %v", err)
}

func (*TestFramework) WaitOutputPresent ¶

func (f *TestFramework) WaitOutputPresent(cmd string, checker func(string) bool, timeout time.Duration) error

WaitOutputPresent repeatedly executes a command until the output satisfies the provided checker function or the timeout expires. This utility method is used for waiting on asynchronous operations and service readiness verification.

The method polls the command output at regular intervals (100ms) and applies the checker function to determine if the expected condition has been met. This is particularly useful for waiting on service startup, configuration application, or system state changes.

Parameters:

• cmd: Shell command to execute repeatedly
• checker: Function that returns true when the desired condition is met
• timeout: Maximum time to wait for the condition

Returns:

• error: An error if the timeout expires or command execution fails

Example:

err := fw.WaitOutputPresent("ps aux | grep yanet", func(output string) bool {
    return strings.Contains(output, "yanet-dataplane")
}, 30*time.Second)

func (*TestFramework) WriteGuestFile ¶

func (f *TestFramework) WriteGuestFile(path string, contents string) error

WriteGuestFile writes a file into the guest filesystem.

func (*UDPBuilder) Build ¶

func (b *UDPBuilder) Build() gopacket.SerializableLayer

func (*VMPool) Acquire ¶

func (p *VMPool) Acquire() *TestFramework

Acquire blocks until a VM slot is available and returns its framework instance. The caller MUST call Release when done.

func (*VMPool) ForEachParallel ¶

func (p *VMPool) ForEachParallel(fn func(idx int, fw *TestFramework) error) error

ForEachParallel calls fn for each VM's framework instance in parallel.

func (*VMPool) ForceStop ¶

func (p *VMPool) ForceStop()

ForceStop makes every VM in the pool ignore the test keep-alive setting.

func (*VMPool) Release ¶

func (p *VMPool) Release(fw *TestFramework)

Release returns a VM slot back to the pool.

func (*VMPool) Shutdown ¶

func (p *VMPool) Shutdown() error

Shutdown stops all VM slots in the pool.

func (*VMPool) Size ¶

func (p *VMPool) Size() int

Size returns the number of VM slots in the pool.

func (*VMPool) StartAll ¶

func (p *VMPool) StartAll() error

StartAll starts all VM slots. It prefers the configured template overlay when available and otherwise falls back to the cached booted template.

• Fast path: preferred template or booted template already exists -> copy it to each slot and boot via -loadvm <snapshot>.
• Slow path: booted template missing -> boot VM0 from scratch, save the booted snapshot, cache it as the template, then restart all slots from it.

After StartAll all slots are added to the available channel.

func (*VMPool) StopAllCPU ¶

func (p *VMPool) StopAllCPU()

StopAllCPU pauses every VM's CPU via the QEMU monitor. Useful after initial setup to avoid idle DPDK busy-polling consuming host CPU.

func (*VMPool) WaitAllReady ¶

func (p *VMPool) WaitAllReady(timeout time.Duration) error

WaitAllReady waits for every VM in the pool to reach the shell prompt.