From 4965202fb03299fc351f20eb2eb13f3fa30f6704 Mon Sep 17 00:00:00 2001
From: skal <pascal.massimino@gmail.com>
Date: Sat, 7 Feb 2026 09:46:12 +0100
Subject: test: Add GPU effects test infrastructure (Phase 1 Foundation)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Creates shared testing utilities for headless GPU effect testing.
Enables testing visual effects without windows (CI-friendly).

New Test Infrastructure (8 files):
- webgpu_test_fixture.{h,cc}: Shared WebGPU initialization
  * Handles Win32 (old API) vs Native (new callback info structs)
  * Graceful skip if GPU unavailable
  * Eliminates 100+ lines of boilerplate per test

- offscreen_render_target.{h,cc}: Headless rendering ("frame sink")
  * Creates offscreen WGPUTexture for rendering without windows
  * Pixel readback via wgpuBufferMapAsync for validation
  * 262,144 byte framebuffer (256x256 BGRA8)

- effect_test_helpers.{h,cc}: Reusable validation utilities
  * has_rendered_content(): Detects non-black pixels
  * all_pixels_match_color(): Color matching with tolerance
  * hash_pixels(): Deterministic output verification (FNV-1a)

- test_effect_base.cc: Comprehensive test suite (7 tests, all passing)
  * WebGPU fixture lifecycle
  * Offscreen rendering and pixel readback
  * Effect construction and initialization
  * Sequence add_effect and activation logic
  * Pixel validation helpers

Coverage Impact:
- GPU test infrastructure: 0% → Foundation ready for Phase 2
- Next: Individual effect tests (FlashEffect, GaussianBlur, etc.)

Size Impact: ZERO
- All test code wrapped in #if !defined(STRIP_ALL)
- Test executables separate from demo64k
- No impact on final binary (verified with guards)

Test Output:
  ✓ 7/7 tests passing
  ✓ WebGPU initialization (adapter + device)
  ✓ Offscreen render target creation
  ✓ Pixel readback (262,144 bytes)
  ✓ Effect initialization via Sequence
  ✓ Sequence activation logic
  ✓ Pixel validation helpers

Technical Details:
- Uses WGPUTexelCopyTextureInfo/BufferInfo (not deprecated ImageCopy*)
- Handles WGPURequestAdapterCallbackInfo (native) vs old API (Win32)
- Polls wgpuInstanceProcessEvents for async operations
- MapAsync uses WGPUMapMode_Read for pixel readback

Analysis Document:
- GPU_EFFECTS_TEST_ANALYSIS.md: Full roadmap (Phases 1-4, 44 hours)
- Phase 1 complete, Phase 2 ready (individual effect tests)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 src/tests/effect_test_helpers.h | 54 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)
 create mode 100644 src/tests/effect_test_helpers.h

(limited to 'src/tests/effect_test_helpers.h')

diff --git a/src/tests/effect_test_helpers.h b/src/tests/effect_test_helpers.h
new file mode 100644
index 0000000..d48daa7
--- /dev/null
+++ b/src/tests/effect_test_helpers.h
@@ -0,0 +1,54 @@
+// This file is part of the 64k demo project.
+// It provides reusable test helpers for GPU effect testing.
+// Includes lifecycle helpers, pixel validation, and smoke tests.
+
+#pragma once
+
+#include <cstdint>
+#include <functional>
+#include <vector>
+
+// Forward declarations
+class Effect;
+class MainSequence;
+
+// ============================================================================
+// Pixel Validation Helpers
+// ============================================================================
+
+// Validate pixels using a predicate function
+// Returns true if at least one pixel matches the predicate
+bool validate_pixels(
+    const std::vector<uint8_t>& pixels,
+    int width,
+    int height,
+    std::function<bool(uint8_t r, uint8_t g, uint8_t b, uint8_t a)> predicate);
+
+// Check if any pixel is non-black (rendered something)
+bool has_rendered_content(const std::vector<uint8_t>& pixels,
+                          int width,
+                          int height);
+
+// Check if all pixels match a specific color (within tolerance)
+bool all_pixels_match_color(const std::vector<uint8_t>& pixels,
+                             int width,
+                             int height,
+                             uint8_t r,
+                             uint8_t g,
+                             uint8_t b,
+                             uint8_t tolerance = 5);
+
+// Compute simple hash of pixel data (for deterministic output checks)
+uint64_t hash_pixels(const std::vector<uint8_t>& pixels);
+
+// ============================================================================
+// Effect Lifecycle Helpers
+// ============================================================================
+
+// Test that an effect can be constructed and initialized
+// Returns true if lifecycle succeeds, false otherwise
+bool test_effect_lifecycle(Effect* effect, MainSequence* main_seq);
+
+// Test that an effect can render without crashing (smoke test)
+// Does not validate output, only checks for crashes
+bool test_effect_render_smoke(Effect* effect);
-- 
cgit v1.2.3