Vitest Testing & Fixtures

Relevant source files

The following files were used as context for generating this wiki page:

• vitest.config.ts
• test/basic.test.ts
• test/findInterfaces.test.ts
• test/setInterfaceMAC.test.ts
• test/cli.test.ts
• test/oui.test.ts
• package.json
• stryker.config.json

The spoof project utilizes Vitest as its primary testing framework to ensure cross-platform compatibility and reliability of MAC address spoofing operations. The testing strategy combines unit tests for pure utility functions, platform-specific integration tests using mocked system commands, and CLI-level validation.

The test suite is designed to simulate various operating systems (macOS, Linux, and Windows) by intercepting system-level calls. This allows the project to maintain high code quality and prevent regressions across different environments without requiring actual hardware or root privileges during the continuous integration process.

Sources: vitest.config.ts:3-28, package.json:20-27, test/findInterfaces.test.ts:1-12

Testing Infrastructure & Configuration

The testing environment is configured to run in a Node.js environment using the V8 coverage provider. Key configuration settings prioritize strict isolation and comprehensive reporting.

Configuration Option	Value	Description
environment	node	Executes tests in a Node.js context.
globals	false	Requires explicit imports of describe, it, and expect.
include	['test/**/*.test.ts', 'test/**/*.test.js']	Patterns for identifying test files.
testTimeout	20000	Global timeout for individual tests (20 seconds).
coverage.include	['src/**/*.ts']	Files included in coverage metrics.
coverage.exclude	src/types.ts, src/cli.ts, **/*.d.ts	Files excluded from coverage analysis.

Sources: vitest.config.ts:5-24

Mutation Testing

The project integrates Stryker to perform mutation testing, which evaluates the effectiveness of the Vitest suite by injecting "mutants" (logic changes) into the source code to see if tests fail as expected.

The diagram illustrates how Stryker uses the Vitest runner to validate the robustness of the existing test cases.
Sources: stryker.config.json:1-16

Mocking System Commands

Because the core functionality of spoof relies on executing shell commands (e.g., ifconfig, ip link, networksetup), the project uses vi.doMock to intercept child_process calls. This allows tests to return platform-specific "fixtures"—raw text outputs from actual system commands—to verify the parser logic.

Mock Creation Patterns

Tests often employ a helper function to create consistent mocks for both synchronous and asynchronous process execution.

function createChildProcessMock(mockExecSync: (cmd: string) => Buffer) {
  const mockExecFileSync = (cmd: string, args?: string[]) => {
    const fullCmd = args ? [cmd, ...args].join(' ') : cmd
    return mockExecSync(fullCmd)
  }
  return {
    execSync: mockExecSync,
    execFileSync: mockExecFileSync,
    exec: vi.fn(),
    execFile: vi.fn(),
    // ... other child_process methods
  }
}

Sources: test/findInterfaces.test.ts:25-40, test/setInterfaceMAC.test.ts:13-28

Fixture-Based Validation

Fixtures are stored as .txt files in test/fixtures/[platform]/ and are loaded during test execution to simulate realistic system responses.

This flow shows how the test suite uses raw text fixtures to validate that the library's internal parsers correctly identify network hardware across different operating systems.
Sources: test/findInterfaces.test.ts:16-23, test/findInterfaces.test.ts:57-75

Specialized Test Suites

Interface Discovery (findInterfaces)

These tests verify that the library correctly identifies network devices on different platforms.

• macOS (Darwin): Mocks networksetup -listallhardwareports and ifconfig.
• Linux: Validates both modern ip link show (iproute2) and legacy ifconfig outputs.
• Windows: Mocks ipconfig /all and getmac /v /fo csv.

Sources: test/findInterfaces.test.ts:46-48, test/findInterfaces.test.ts:104-106, test/findInterfaces.test.ts:208-210

MAC Address Operations (setInterfaceMAC)

Validation tests focus on error handling and platform-specific command construction.

• Input Validation: Rejects invalid formats like GG:GG:GG... or 00.00.00... while accepting standard colons and dashes.
• Linux Logic: Verifies that the ip command sequence (down -> address -> up) is called in the correct order.
• Windows Registry: Uses a mocked winreg module to verify that the NetworkAddress is set in the correct Registry hive (HKLM\SYSTEM\CurrentControlSet\Control\Class\...).

Sources: test/setInterfaceMAC.test.ts:74-90, test/setInterfaceMAC.test.ts:176-192, test/setInterfaceMAC.test.ts:401-417

OUI Vendor Database

Tests for the oui module ensure that MAC address lookups and randomized vendor spoofing function correctly using the bundled database.

• Lookup: Checks case-insensitivity and multiple formats (Cisco-style, dot notation).
• Fuzzy Search: Validates Levenshtein distance matching for vendor names (e.g., "Aplle" finds "Apple").
• Randomization: Ensures generated addresses have the correct vendor prefix and, if requested, the "locally administered" bit set.

Sources: test/oui.test.ts:18-45, test/oui.test.ts:114-128, test/oui.test.ts:193-200

CLI Integration Testing

The CLI is tested by executing the built binary (dist/cli.js) using execFileSync. This ensures that minimist argument parsing and chalk-based formatting work as intended.

Command Tested	Validation Logic
help	Checks for usage instructions and option descriptions.
version	Validates Semantic Versioning regex ^\d+\.\d+\.\d+.
normalize	Confirms various input formats result in uppercase colon-separated MACs.
--format=json	Ensures the output is valid JSON and contains the success field.
--dry-run	Verifies the CLI exits with code 2 when an operation would fail.

Sources: test/cli.test.ts:13-33, test/cli.test.ts:102-110, test/cli.test.ts:260-268, test/cli.test.ts:326-335

Conclusion

The Vitest suite provides a comprehensive safety net for the spoof project by abstracting complex system interactions. By combining fixture-based mocking for hardware discovery with strict integration tests for the CLI, the project ensures that MAC address spoofing remains reliable across macOS, Linux, and Windows platforms.