pcbjam/docs/04-COMPREHENSIVE-WASM-TEST.md

Phase 4: Comprehensive wxWidgets WASM Test Application

Overview

Create a multi-widget showcase test application for the wxWidgets WASM port that thoroughly exercises wxUniversal controls and event handling. This validates the WASM port before integrating KiCad components.

Goal

1. Display various wxUniversal controls in a tabbed interface
2. Support full interaction: mouse clicks, keyboard input, mouse drag/draw, hover effects
3. Show an on-screen event log panel for visual verification
4. Have corresponding Playwright tests to verify all interactions work

---

Application Architecture

+-------------------------------------------------------+
|  Menu: File | Edit | Help                             |
+-------------------------------------------------------+
|  [Controls Tab] [Text Tab] [Drawing Tab] [Lists Tab]  |
+-------------------------------------------------------+
|                                                       |
|                  Tab Content Area                     |
|                  (varies by tab)                      |
|                                                       |
+-------------------------------------------------------+
|  Event Log Panel (wxListBox)                          |
|  - "Button 'Test' clicked"                            |
|  - "Checkbox toggled: checked"                        |
|  - "Mouse moved to (123, 456)"                        |
+-------------------------------------------------------+
|  Status Bar: Ready                                    |
+-------------------------------------------------------+

---

Files to Modify

File	Action	Description
tests/wasm-app/minimal_test.cpp	Replace	Comprehensive widget showcase
tests/e2e/wxwidgets.spec.ts	Update	Add interaction tests

---

Test Application Structure

Control IDs

enum {
    ID_BTN_TEST = wxID_HIGHEST + 1,
    ID_BTN_TOGGLE,
    ID_CHK_FEATURE,
    ID_RADIO_OPTIONS,
    ID_SLIDER,
    ID_GAUGE,
    ID_TEXT_SINGLE,
    ID_TEXT_MULTI,
    ID_TEXT_PASSWORD,
    ID_COMBO,
    ID_LISTBOX,
    ID_CHOICE,
    ID_BTN_CLEAR,
    ID_EVENT_LOG,
    ID_DRAWING_PANEL
};

Main Classes

class TestApp : public wxApp;           // Application entry point
class TestFrame : public wxFrame;        // Main frame with notebook and event log
class ControlsPage : public wxPanel;     // Tab 1: Buttons, checkboxes, sliders
class TextPage : public wxPanel;         // Tab 2: Text controls
class DrawingPage : public wxPanel;      // Tab 3: Mouse drawing canvas
class ListsPage : public wxPanel;        // Tab 4: Lists and dropdowns
class DrawingPanel : public wxPanel;     // Custom drawing canvas

---

Tab Contents

Tab 1: Controls

Control	ID	Purpose
wxButton ("Click Me")	ID_BTN_TEST	Basic click event
wxToggleButton ("Toggle")	ID_BTN_TOGGLE	Two-state button
wxCheckBox ("Enable feature")	ID_CHK_FEATURE	Boolean toggle
wxRadioBox ("Options": A/B/C)	ID_RADIO_OPTIONS	Exclusive selection
wxSlider (0-100)	ID_SLIDER	Range selection
wxGauge	ID_GAUGE	Shows slider value

Tab 2: Text Input

Control	ID	Purpose
wxTextCtrl (single-line)	ID_TEXT_SINGLE	Basic text input
wxTextCtrl (multi-line)	ID_TEXT_MULTI	Multi-line text
wxTextCtrl (password)	ID_TEXT_PASSWORD	Masked input
wxComboBox	ID_COMBO	Dropdown with text

Tab 3: Drawing Canvas

Control	ID	Purpose
DrawingPanel	ID_DRAWING_PANEL	Custom painting
wxButton ("Clear")	ID_BTN_CLEAR	Reset canvas

Mouse interactions:

• wxEVT_LEFT_DOWN - Start drawing
• wxEVT_MOTION - Draw line segments
• wxEVT_LEFT_UP - End drawing

Tab 4: Lists

Control	ID	Purpose
wxListBox	ID_LISTBOX	Multi-item selection
wxChoice	ID_CHOICE	Dropdown selection
Add/Remove buttons	-	Modify list contents

---

Event Log Panel

• wxListBox at bottom of frame
• ID: ID_EVENT_LOG
• Max 100 entries (older entries removed)
• Auto-scrolls to bottom
• Format: "[HH:MM:SS] Event description"

Events also logged to browser console for Playwright verification.

---

Event Types to Test

Event	Control	Test Method
wxEVT_BUTTON	Button	Click canvas coordinates
wxEVT_TOGGLEBUTTON	ToggleButton	Click and verify state
wxEVT_CHECKBOX	CheckBox	Click and verify checked
wxEVT_RADIOBOX	RadioBox	Click option and verify
wxEVT_SLIDER	Slider	Drag and verify value
wxEVT_TEXT	TextCtrl	Type and verify content
wxEVT_TEXT_ENTER	TextCtrl	Press Enter
wxEVT_LISTBOX	ListBox	Click item and verify
wxEVT_CHOICE	Choice	Click and select
wxEVT_LEFT_DOWN	Panel	Mouse down
wxEVT_MOTION	Panel	Mouse move
wxEVT_LEFT_UP	Panel	Mouse up
wxEVT_PAINT	Panel	Automatic on invalidate

---

Playwright Test Structure

test.describe('wxWidgets WASM Comprehensive', () => {
  // Existing loading tests...

  test.describe('Controls Tab', () => {
    test('button click logs event');
    test('checkbox toggle works');
    test('slider interaction');
    test('radio button selection');
  });

  test.describe('Text Input Tab', () => {
    test('text input accepts keyboard');
    test('multiline text input');
    test('password field masks input');
  });

  test.describe('Drawing Tab', () => {
    test('mouse drag draws on canvas');
    test('clear button resets canvas');
  });

  test.describe('Lists Tab', () => {
    test('listbox selection');
    test('choice dropdown');
  });

  test.describe('Event Log', () => {
    test('events are logged visually');
  });
});

Test Helpers

// Wait for app to be ready
async function waitForApp(page: Page) {
  await page.waitForSelector('canvas', { state: 'visible', timeout: 30000 });
  await page.waitForTimeout(500); // Let UI settle
}

// Simulate click at canvas coordinates
async function clickAt(page: Page, x: number, y: number) {
  const canvas = page.locator('canvas');
  await canvas.click({ position: { x, y } });
}

// Check console for event log entries
async function getConsoleEvents(page: Page): Promise<string[]> {
  // Capture console.log messages with [EVENT] prefix
}

---

Testing Challenges & Solutions

Challenge 1: Canvas Coordinate Mapping

wxUniversal renders all widgets to a single HTML5 canvas. Tests need to know widget positions.

Solution: Use consistent layout with predictable positions. Log control bounds to console on startup.

Challenge 2: Verifying Event Log Content

The event log is inside the WASM app, not directly accessible from JavaScript.

Solution: Log events to browser console with [EVENT] prefix. Playwright captures via page.on('console').

Challenge 3: Keyboard Input

Need to route keyboard events to the correct wxWidgets control.

Solution: Focus canvas first, then use page.keyboard.type(). wxWidgets handles focus internally.

---

wxUniversal Controls Reference

Available controls in wxUniversal (verified in wxwidgets/include/wx/univ/):

Buttons:

• wxButton, wxBitmapButton, wxToggleButton

Input Controls:

• wxCheckBox, wxRadioButton, wxRadioBox
• wxTextCtrl (single/multi-line)
• wxComboBox, wxChoice

Lists:

• wxListBox, wxCheckListBox

Range Controls:

• wxSlider, wxGauge, wxSpinButton

Containers:

• wxNotebook (tabbed container)
• wxPanel, wxScrolledWindow

Static Controls:

• wxStaticText, wxStaticBox, wxStaticLine

Frame Elements:

• wxMenu, wxMenuBar, wxStatusBar

---

Implementation Steps

Step 1: Update minimal_test.cpp

Replace current minimal test with comprehensive widget showcase.

Key components:

1. TestFrame constructor creates notebook, tabs, and event log
2. Each tab page creates its controls with appropriate sizers
3. Event handlers call LogEvent() to record actions
4. LogEvent() adds to wxListBox AND prints to console

Step 2: Update Playwright Tests

Extend tests/e2e/wxwidgets.spec.ts:

1. Keep existing loading tests
2. Add test groups for each tab
3. Add console event capture
4. Add canvas interaction helpers

Step 3: Build and Test

# Rebuild test app
./scripts/build-wasm-test.sh

# Run tests
cd tests && npm test

# Visual debugging
npm run test:ui
# or
cd wasm-app && npx serve .

---

Success Criteria

Visual Verification

• App displays with menu bar
• Four tabs visible and switchable
• Controls visible on each tab
• Event log panel at bottom

Interaction Tests

• Button click logs "Button clicked"
• Checkbox toggle logs state change
• Slider drag updates gauge and logs value
• Text input shows typed text and logs changes
• Drawing canvas responds to mouse drag
• ListBox/Choice selection works

Playwright Tests

• All existing loading tests pass
• Button interaction test passes
• Checkbox interaction test passes
• Text input test passes
• Drawing interaction test passes

---

Dependencies

Before implementation:

• wxWidgets WASM build complete (./scripts/build-wxuniversal-wasm.sh)
• Existing Playwright tests passing (cd tests && npm test)

---

References

• wxWidgets Samples: wxwidgets/samples/widgets/ - Multi-widget showcase pattern
• wxWidgets Samples: wxwidgets/samples/drawing/ - Custom painting pattern
• wxUniversal Headers: wxwidgets/include/wx/univ/ - Available controls