| 1 | ## Test Generation Guidelines for WSL |
| 2 | |
| 3 | When generating tests for this repository, follow these patterns: |
| 4 | |
| 5 | ### Framework |
| 6 | Tests use TAEF (Test Authoring and Execution Framework). Always include `"Common.h"`. |
| 7 | |
| 8 | ### Test Class Structure |
| 9 | ```cpp |
| 10 | #include "Common.h" |
| 11 | |
| 12 | namespace MyFeatureTests |
| 13 | { |
| 14 | class MyFeatureTests |
| 15 | { |
| 16 | WSL_TEST_CLASS(MyFeatureTests) |
| 17 | |
| 18 | TEST_CLASS_SETUP(TestClassSetup) |
| 19 | { |
| 20 | VERIFY_ARE_EQUAL(LxsstuInitialize(FALSE), TRUE); |
| 21 | return true; |
| 22 | } |
| 23 | |
| 24 | TEST_CLASS_CLEANUP(TestClassCleanup) |
| 25 | { |
| 26 | LxsstuUninitialize(FALSE); |
| 27 | return true; |
| 28 | } |
| 29 | |
| 30 | TEST_METHOD(DescriptiveTestName) |
| 31 | { |
| 32 | // Test implementation |
| 33 | } |
| 34 | }; |
| 35 | } |
| 36 | ``` |
| 37 | |
| 38 | ### Key Rules |
| 39 | - Use `WSL_TEST_CLASS(Name)` — never raw `BEGIN_TEST_CLASS` |
| 40 | - Setup/cleanup methods must `return true` on success |
| 41 | - Use `VERIFY_*` macros for assertions — never `assert()` or exceptions for test validation |
| 42 | |
| 43 | ### Assertion Macros |
| 44 | - `VERIFY_ARE_EQUAL(expected, actual)` — value equality |
| 45 | - `VERIFY_ARE_NOT_EQUAL(a, b)` — value inequality |
| 46 | - `VERIFY_IS_TRUE(condition)` — boolean check |
| 47 | - `VERIFY_IS_FALSE(condition)` — negative boolean check |
| 48 | - `VERIFY_IS_NULL(ptr)` — null check |
| 49 | - `VERIFY_IS_NOT_NULL(ptr)` — non-null check |
| 50 | - `VERIFY_WIN32_BOOL_SUCCEEDED(expr)` — Win32 BOOL result |
| 51 | - `VERIFY_SUCCEEDED(hr)` — HRESULT success |
| 52 | |
| 53 | ### Logging in Tests |
| 54 | - `LogInfo(fmt, ...)` — informational messages |
| 55 | - `LogError(fmt, ...)` — error messages |
| 56 | - `LogWarning(fmt, ...)` — warnings |
| 57 | - `LogPass(fmt, ...)` — explicit pass messages |
| 58 | - `LogSkipped(fmt, ...)` — skip messages |
| 59 | |
| 60 | ### Conditional Skipping |
| 61 | Add skip macros at the start of a test method body when the test only applies to certain environments: |
| 62 | ```cpp |
| 63 | TEST_METHOD(Wsl2SpecificTest) |
| 64 | { |
| 65 | WSL2_TEST_ONLY(); |
| 66 | // ... test code ... |
| 67 | } |
| 68 | ``` |
| 69 | |
| 70 | Available skip macros: |
| 71 | - `WSL1_TEST_ONLY()` — skip unless WSL1 |
| 72 | - `WSL2_TEST_ONLY()` — skip unless WSL2 |
| 73 | - `SKIP_TEST_ARM64()` — skip on ARM64 |
| 74 | - `SKIP_TEST_UNSTABLE()` — skip known-flaky tests |
| 75 | - `WINDOWS_11_TEST_ONLY()` — skip on pre-Windows 11 |
| 76 | - `WSL_TEST_VERSION_REQUIRED(version)` — skip if WSL version too old |
| 77 | |
| 78 | ### RAII Test Helpers |
| 79 | - `WslKeepAlive` — prevents UVM timeout during long-running tests; create at test start |
| 80 | - `WslConfigChange` — RAII wrapper that applies a temporary `.wslconfig` and restores the original on destruction: |
| 81 | ```cpp |
| 82 | TEST_METHOD(TestWithCustomConfig) |
| 83 | { |
| 84 | WslConfigChange config(L"[wsl2]\nmemory=4GB\n"); |
| 85 | // ... test with custom config ... |
| 86 | // Original .wslconfig restored when config goes out of scope |
| 87 | } |
| 88 | ``` |
| 89 | |
| 90 | ### Memory in Tests |
| 91 | - Use `ALLOC(size)` / `FREE(ptr)` macros for direct heap allocation in tests |
| 92 | - Prefer RAII wrappers and smart pointers for production-like code paths |
| 93 | |
| 94 | ### Test Naming |
| 95 | - Use descriptive PascalCase names that describe the scenario: `CreateInstanceWithInvalidGuidFails`, `EchoTest`, `MountPlan9Share` |
| 96 | - Group related tests in the same test class |