#Test Generation Guidelines for WSL

When generating tests for this repository, follow these patterns:

#Framework

Tests use TAEF (Test Authoring and Execution Framework). Always include "Common.h".

#Test Class Structure

#include "Common.h"

namespace MyFeatureTests
{
class MyFeatureTests
{
    WSL_TEST_CLASS(MyFeatureTests)

    TEST_CLASS_SETUP(TestClassSetup)
    {
        VERIFY_ARE_EQUAL(LxsstuInitialize(FALSE), TRUE);
        return true;
    }

    TEST_CLASS_CLEANUP(TestClassCleanup)
    {
        LxsstuUninitialize(FALSE);
        return true;
    }

    TEST_METHOD(DescriptiveTestName)
    {
        // Test implementation
    }
};
}

#Key Rules

• Use WSL_TEST_CLASS(Name) — never raw BEGIN_TEST_CLASS
• Setup/cleanup methods must return true on success
• Use VERIFY_* macros for assertions — never assert() or exceptions for test validation

#Assertion Macros

• VERIFY_ARE_EQUAL(expected, actual) — value equality
• VERIFY_ARE_NOT_EQUAL(a, b) — value inequality
• VERIFY_IS_TRUE(condition) — boolean check
• VERIFY_IS_FALSE(condition) — negative boolean check
• VERIFY_IS_NULL(ptr) — null check
• VERIFY_IS_NOT_NULL(ptr) — non-null check
• VERIFY_WIN32_BOOL_SUCCEEDED(expr) — Win32 BOOL result
• VERIFY_SUCCEEDED(hr) — HRESULT success

#Logging in Tests

• LogInfo(fmt, ...) — informational messages
• LogError(fmt, ...) — error messages
• LogWarning(fmt, ...) — warnings
• LogPass(fmt, ...) — explicit pass messages
• LogSkipped(fmt, ...) — skip messages

#Conditional Skipping

Add skip macros at the start of a test method body when the test only applies to certain environments: cpp TEST_METHOD(Wsl2SpecificTest) { WSL2_TEST_ONLY(); // ... test code ... }

Available skip macros: - WSL1_TEST_ONLY() — skip unless WSL1 - WSL2_TEST_ONLY() — skip unless WSL2 - SKIP_TEST_ARM64() — skip on ARM64 - SKIP_TEST_UNSTABLE() — skip known-flaky tests - WINDOWS_11_TEST_ONLY() — skip on pre-Windows 11 - WSL_TEST_VERSION_REQUIRED(version) — skip if WSL version too old

#RAII Test Helpers

• WslKeepAlive — prevents UVM timeout during long-running tests; create at test start
• WslConfigChange — RAII wrapper that applies a temporary .wslconfig and restores the original on destruction: cpp TEST_METHOD(TestWithCustomConfig) { WslConfigChange config(L"[wsl2]\nmemory=4GB\n"); // ... test with custom config ... // Original .wslconfig restored when config goes out of scope }

#Memory in Tests

• Use ALLOC(size) / FREE(ptr) macros for direct heap allocation in tests
• Prefer RAII wrappers and smart pointers for production-like code paths

#Test Naming

• Use descriptive PascalCase names that describe the scenario: CreateInstanceWithInvalidGuidFails, EchoTest, MountPlan9Share
• Group related tests in the same test class