Instructions for Agent

How This Skill is Invoked

In VS Code, users will activate this skill by:

• •Typing @workspace /testing [description] in Copilot Chat
• •Or asking: "Write a test for [feature]", "Add visual regression tests", "Review my test code"

When activated, write tests that strictly follow the project's testing standards.

Core Approach: Standards-First Testing

Every test MUST follow the Arrange-Act-Assert (AAA) pattern with all three phases as separate sections.

Before writing any test, load and review references/TESTING_EXAMPLES.md for concrete examples of correct and incorrect patterns.

Step 1: Determine Test Type

Ask the user what they need:

"What would you like to test? I support:

1. •Unit tests — Test a single class/function in isolation
2. •Integration tests — Test component interactions
3. •Visual regression tests — Compare images pixel-by-pixel
4. •Test review — Check existing tests against our standards"

Step 2: Write Tests Following AAA Pattern

The Three Phases (ALWAYS separate)

Every test MUST have three distinct comment sections:

TEST(SuiteName, MethodName_Condition_ExpectedResult)
{
    // Arrange
    // Set up test preconditions, create objects, define expected values

    // Act
    // Execute the single operation being tested

    // Assert
    // Verify the outcome
}

Critical Rules

1. •NEVER combine phases. Do not write // Arrange & Act or // Act & Assert. Each phase gets its own comment and section.
   • •Exception: // Act & Assert is acceptable only for EXPECT_NO_THROW/EXPECT_THROW tests where the action IS the assertion.
2. •If no Arrange is needed, omit // Arrange entirely — start with // Act.
3. •Move expected values to Arrange as named variables, not inline in Assert.
4. •One logical concept per test — split if testing multiple behaviors.

Naming Convention

Use format: UnitName_StateUnderTest_ExpectedResult

Examples:

• •MoveForward_IncreasesZPosition
• •Compare_IdenticalImages_ReturnsMatch
• •ParsePPM_InvalidFile_ReturnsEmptyData

Step 3: Choose the Right Test Pattern

Unit Tests (tests/core/)

Test a single class method in isolation. Use MockOpenGL for OpenGL calls.

TEST(CameraTest, MoveForward_DefaultSpeed_IncreasesPosition)
{
    // Arrange
    Camera camera(800, 600);
    camera.cameraPos = glm::vec3(0.0f, 0.0f, 0.0f);
    camera.setSpeed(1.0f);

    // Act
    camera.moveForward();

    // Assert
    EXPECT_LT(camera.cameraPos.z, 0.0f);
}

Integration Tests (tests/integration/)

Test component interactions. May involve multiple classes.

TEST(DataLoadingPipelineTest, LoadSettings_ValidFile_PopulatesParticles)
{
    // Arrange
    SettingsIO settings;
    std::string test_file = createTestSettingsFile();

    // Act
    bool result = settings.loadSettings(test_file);

    // Assert
    EXPECT_TRUE(result);
    EXPECT_GT(settings.getParticleCount(), 0u);
}

Visual Regression Tests (tests/visual-regression/)

Use production classes (e.g., Particle) directly — never duplicate production logic in test helpers. Use PixelComparator and the Image class for pixel comparison.

TEST_F(RenderingRegressionTest, RenderDefaultCube_AngledView_MatchesBaseline)
{
    // Arrange
    Shader particleShader(vertexPath.c_str(), fragmentPath.c_str());
    Particle particles;  // Uses production Particle class directly
    glm::mat4 view = glm::lookAt(cameraPos, cameraTarget, cameraUp);
    glm::mat4 projection = glm::perspective(glm::radians(45.0f), aspect, 0.1f, 3000.0f);

    // Act
    glContext_.bindFramebuffer();
    renderParticle(particles, particleShader, view, projection);
    Image currentImage = glContext_.captureFramebuffer();

    // Assert
    Image baseline = Image::load(baselinePath, ImageFormat::PNG);
    PixelComparator comparator;
    ComparisonResult result = comparator.compare(baseline, currentImage, tolerance, true);
    EXPECT_TRUE(result.matches);
}

Step 4: Apply Test File Organization

Directory Structure

• •tests/core/ — Unit tests for src/*.hpp classes
• •tests/integration/ — Multi-component tests
• •tests/testing/ — Tests for test utilities (PixelComparator, Image)
• •tests/visual-regression/ — Visual regression tests
• •tests/mocks/ — Mock implementations

File Naming

Each test file matches its source: CameraTests.cpp tests camera.hpp.

Test Ordering

Within a file, order tests: basic → complex, common → edge cases.

Step 5: Self-Review Checklist

Before presenting tests, verify:

• • Every test has separate // Arrange, // Act, // Assert comments (no // Arrange & Act)
• • Test name follows UnitName_StateUnderTest_ExpectedResult pattern
• • Expected values are named variables in Arrange (not inline literals in Assert)
• • One logical concept per test
• • External dependencies are mocked (OpenGL, file I/O)
• • No testing of external libraries (std::, third-party code)
• • Visual regression tests use production classes (Particle, Camera) — no duplicated test helpers
• • Group related configuration into structs/POCOs instead of flat variables
• • Resource cleanup: GL objects deleted in destructors/cleanup, check for leaks
• • Test SetUp() ensures all output directories exist (artifacts/, baselines/, diffs/)
• • Artifact save() return values are checked, not silently ignored
• • Visual test resolution matches viewer defaults (1280x720) unless specifically testing other resolutions
• • Tests compile and pass

Key Design Principles (Learned from Review Feedback)

1. •

   Use production classes in tests. Visual regression tests should use Particle directly instead of re-implementing particle creation logic in a test helper class. This ensures tests stay in sync with production code.

2. •

   Group related data into POCOs/structs. When a test or test helper has many flat member variables, group them into domain-specific structs (e.g., RenderConfig, CameraSetup). This mirrors the production code pattern.

3. •

   Clean up GL resources. Every test that creates GL objects (VAOs, VBOs, FBOs, textures) must clean them up. Check for leaks in cleanup() / destructors.

4. •

   Binary file I/O. Always open binary data files with "rb" mode (not "r") for cross-platform correctness.

5. •

   Ensure output directories exist. In test SetUp(), create all output directories (artifacts/, baselines/, diffs/) before tests run. Check save() return values so failures are actionable, not silent.

6. •

   Visual test resolution. Use the viewer's default resolution (1280x720) for visual regression tests unless specifically testing other resolutions. Non-default resolutions can cause warping and scaling artifacts.

7. •

   Camera positioning for visual tests. Don't blindly copy debug camera coordinates — debug shows interactive state, not ideal test framing. Extract the viewing direction from debug output, then calculate distance based on desired viewport coverage: distance = subject_size / (coverage_% * tan(FOV/2)). See docs/visual-regression/camera-positioning-lessons-learned.md.

Self-Evaluation

After completing test work, run the self-evaluation skill (.github/skills/self-evaluation/) to capture any new testing patterns learned during the session.

Key Types for Visual Regression

Common Edge Cases to Handle

• •Ask if the user wants EXPECT_* (non-fatal) or ASSERT_* (fatal) assertions
• •For visual tests: recommend 0.0f tolerance for synthetic data, 2.0f/255.0f for GPU-rendered
• •If a test seems to test external library behavior, suggest focusing on the wrapper/integration instead
• •If Arrange and Act seem identical, the test might be a constructor test — put expected values in Arrange, constructor call in Act

CI Pipeline Rules

For CI workflow rules (artifact uploads, permissions, PR comments), see the workflow skill (.github/skills/workflow/).