| name | qa-test |
| description | Create a manual QA test checklist for a DRAW feature or tool. Generates a hierarchical checklist in PLANS/TESTS/ with test cases derived from state diagrams, keyboard/mouse bindings, source code, and project instructions. |
QA Test — Create Test Checklist
When the user invokes this skill (e.g. "create tests for X", "qa-test for FILL", "test the menubar"), generate a comprehensive manual test checklist for the specified DRAW feature. Follow these steps in order. Do not skip steps.
Step 0 — Accept test subject
Ask the user:
"What feature or area of DRAW should I create tests for?"
The answer becomes {NAME} — used as the filename and title throughout. Normalize to UPPERCASE for filenames (e.g. "fill tool" → FILL, "menubar" → MENUBAR, "layers panel" → LAYERS-PANEL).
If the user already named the feature in their request, skip the question and proceed.
Step 1 — Gather knowledge
Collect context in this priority order (per PLANS/TESTING.md):
1a — Instructions and skills
Read .claude/instructions/draw-project.md (always). Then read any instruction file whose topic matches the feature's source files:
| Feature Area | Instruction File |
|---|
| Mouse/input tools | draw-mouse.md |
| Screen/rendering | draw-rendering.md, draw-chrome-geometry.md |
| UI panels/toolbar/menubar | draw-ui.md, draw-chrome-geometry.md |
| Undo/history | draw-undo.md |
| Text tool | draw-text-tool.md |
| File formats/DRW | draw-fileformat.md |
| Sound/music | draw-sound.md |
1b — State machine diagram
Find the matching diagram in PLANS/diagrams/ using this index:
GLOBAL (system-wide state machines)
| Diagram | File | Covers |
|---|
| Mouse Input | GLOBAL/MOUSE-STATES.DOT | Mouse pipeline, click/drag/release, UI chrome handling |
| Keyboard Input | GLOBAL/KEYBOARD-STATES.DOT | Key dispatch, modifiers, tool shortcuts, hotkey guards |
| UI State | GLOBAL/UI-STATES.DOT | Frame lifecycle, idle detection, scene dirty, render gating |
GUI (panels, bars, and UI components)
| Diagram | File | Covers |
|---|
| Menubar | GUI/MENUBAR-STATES.DOT | Menu open/close, keyboard nav, cascading submenus |
| Layers Panel | GUI/LAYERS-PANEL-STATES.DOT | Layer list, selection, visibility, drag reorder in panel |
| Toolbox | GUI/TOOLBOX-STATES.DOT | Toolbar grid, tool switching, active indicator |
| Organizer | GUI/ORGANIZER-STATES.DOT | 4×3 icon widget, collapsible sections |
| Drawer | GUI/DRAWER-STATES.DOT | 30-slot brush/pattern panel, import/export, context menus |
| Tooltip | GUI/TOOLTIP-STATES.DOT | Hover delay, show/hide, positioning |
| Edit Bar | GUI/EDITBAR-STATES.DOT | Vertical icon bar, docking LEFT/RIGHT, F5 toggle |
| Status Bar | GUI/STATUSBAR-STATES.DOT | Coord display, tool info, mode indicators |
| Palette Strip | GUI/PALETTE-STRIP-STATES.DOT | Color swatches, FG/BG click, scroll |
| Command Palette | GUI/COMMAND-PALETTE-STATES.DOT | Fuzzy search, action dispatch, keyboard nav |
| Preview | GUI/PREVIEW-STATES.DOT | Floating preview, magnifier mode, pan/zoom, resize |
| Dialogs | GUI/DIALOG-STATES.DOT | Modal dialogs, native file pickers, deferred actions |
| Widgets | GUI/WIDGETS-STATES.DOT | Shared widget patterns (scrollbar, checkbox, slider) |
TOOLS (drawing and editing tools)
| Diagram | File | Covers |
|---|
| Text Tool | TOOLS/TEXT-TOOL-STATES.DOT | Text editing, TEXT_BAR, cursor, selection, rich clipboard |
| Dot | TOOLS/DOT-STATES.DOT | Single pixel placement |
| Brush | TOOLS/BRUSH-STATES.DOT | Freehand brush strokes, custom brushes |
| Spray | TOOLS/SPRAY-STATES.DOT | Spray can density/radius |
| Eraser | TOOLS/ERASER-STATES.DOT | Transparent pixel painting |
| Fill | TOOLS/FILL-STATES.DOT | Flood fill, tolerance, fill modes |
| Line | TOOLS/LINE-STATES.DOT | Two-point line drawing |
| Poly Line | TOOLS/POLY-LINE-STATES.DOT | Multi-segment polyline/polygon |
| Rectangle | TOOLS/RECT-STATES.DOT | Rectangle/square drawing |
| Ellipse | TOOLS/ELLIPSE-STATES.DOT | Ellipse/circle drawing |
| Marquee | TOOLS/MARQUEE-STATES.DOT | Selection rectangle, move, copy |
| Move | TOOLS/MOVE-STATES.DOT | Layer/selection movement, nudge |
| Pan | TOOLS/PAN-STATES.DOT | Canvas panning |
| Zoom | TOOLS/ZOOM-STATES.DOT | Canvas zoom in/out |
| Crop | TOOLS/CROP-STATES.DOT | Canvas crop to selection |
| Picker | TOOLS/PICKER-STATES.DOT | Color picker (eyedropper) |
| Save/Load | TOOLS/SAVE-LOAD-STATES.DOT | File save/load, DRW format, recent files |
| Cheatsheet | TOOLS/CHEATSHEET-STATES.DOT | Help overlay rendering |
UTILITIES (assistants and helpers)
| Diagram | File | Covers |
|---|
| Assistants | UTILITIES/ASSISTANTS-STATES.DOT | Drawing assistants overview |
| Crosshair | UTILITIES/CROSSHAIR-STATES.DOT | Crosshair guide lines |
| Picker Loupe | UTILITIES/PICKER-LOUPE-STATES.DOT | Magnified color picker view |
| Symmetry | UTILITIES/SYMMETRY-STATES.DOT | Symmetry modes (H/V/4-way), center control |
| Pattern/Tile | UTILITIES/PATTERN-TILE-STATES.DOT | Pattern and gradient fill modes, Fill-Adj |
| Grid | UTILITIES/GRID-STATES.DOT | Grid snap, display modes, cell fill |
| Brush Size | UTILITIES/BRUSH-SIZE-STATES.DOT | Brush size/shape, presets F1-F4 |
| Color Mode | UTILITIES/COLOR-MODE-STATES.DOT | FG/BG swap, invert, reset |
| Reference Image | UTILITIES/REFIMG-STATES.DOT | Reference image overlay |
LAYER-OPS (layer management operations)
| Diagram | File | Covers |
|---|
| Add/Delete | LAYER-OPS/LAYER-ADD-DELETE-STATES.DOT | New layer, duplicate, delete |
| Merge | LAYER-OPS/LAYER-MERGE-STATES.DOT | Merge down/selected/all, flatten |
| Arrange | LAYER-OPS/LAYER-ARRANGE-STATES.DOT | Reorder up/down/top/bottom, drag |
| Align/Distribute | LAYER-OPS/LAYER-ALIGN-DISTRIBUTE-STATES.DOT | Align 6 dirs, distribute H/V |
| Multiselect | LAYER-OPS/LAYER-MULTISELECT-STATES.DOT | Ctrl/Shift click, solo, visibility swipe |
TRANSFORM-OPS (transformation operations)
| Diagram | File | Covers |
|---|
| Quick Transform | TRANSFORM-OPS/QUICK-TRANSFORM-STATES.DOT | Flip, rotate 90°, scale ±50% |
| Transform Overlay | TRANSFORM-OPS/TRANSFORM-OVERLAY-STATES.DOT | Interactive transform with handles (scale/rotate/shear/distort/perspective) |
IMAGE-OPS (image-level operations)
| Diagram | File | Covers |
|---|
| Resize/Crop | IMAGE-OPS/IMAGE-RESIZE-CROP-STATES.DOT | Canvas resize dialog, crop tool |
| Adjustments | IMAGE-OPS/IMAGE-ADJUSTMENT-STATES.DOT | Brightness, hue, levels, blur, posterize, etc. |
FILE-OPS (file/IO operations)
| Diagram | File | Covers |
|---|
| Import Image | FILE-OPS/IMAGE-IMPORT-STATES.DOT | Image import, placement, resize handles, crop/zoom |
| Extract Images | FILE-OPS/EXTRACT-IMAGES-STATES.DOT | Sprite extraction, component detection, PNG export |
| Load Recent | FILE-OPS/LOAD-RECENT-STATES.DOT | File open, recent files, format detection, state reset |
Read the matching .DOT file and parse:
- States: All labeled nodes
- Transitions: All edges with triggers, guards, and actions
- Sub-state clusters:
subgraph cluster_* blocks
- Error/edge transitions: Timeouts, cancellation, invalid input paths
1c — Source code
Read the relevant .BI and .BM files for the feature. Use this mapping:
| Feature Area | Source Files |
|---|
| Tool states | TOOLS/{TOOLNAME}.BI, TOOLS/{TOOLNAME}.BM |
| GUI panels | GUI/{PANEL}.BI, GUI/{PANEL}.BM |
| Mouse handling | INPUT/MOUSE.BM |
| Keyboard handling | INPUT/KEYBOARD.BM |
| Commands | GUI/COMMAND.BM |
| Rendering | OUTPUT/SCREEN.BM |
| Layer operations | GUI/LAYERS.BM |
| History | TOOLS/HISTORY.BI, TOOLS/HISTORY.BM |
| Configuration | CFG/CONFIG.BI, CFG/CONFIG.BM |
| Image operations | GUI/IMAGE-ADJ.BI, GUI/IMAGE-ADJ.BM |
| Transform | TOOLS/TRANSFORM.BI, TOOLS/TRANSFORM.BM |
| File I/O | INPUT/FILE-*.BM, OUTPUT/FILE-*.BM, TOOLS/DRW.BM |
1d — Keyboard/mouse bindings
Read CHEATSHEET.md and extract all bindings relevant to the feature being tested.
1e — MCP tools (optional)
If the qb64pe MCP server is active, use mcp__qb64pe__lookup_qb64pe_keyword or mcp__qb64pe__search_qb64pe_wiki for any QB64-PE API behaviour that affects the feature's test cases.
Step 2 — Create test file
Create the file PLANS/TESTS/{NAME}.md using this exact template structure:
# [ ] {NAME} TESTING
## [ ] CATEGORY OF TEST
### [ ] SUB-CATEGORY NAME OF TEST
What is being tested. How to test. How to setup for the test.
#### [ ] TEST NAME
1. [ ] Step description
2. [ ] Step description
Rules:
- Every heading level gets a
[ ] checkbox
- Categories group related test areas (e.g. "MOUSE INTERACTIONS", "KEYBOARD SHORTCUTS", "RENDERING", "UNDO/REDO", "STATE TRANSITIONS")
- Sub-categories are more specific groups within a category
- Test names are individual test cases with numbered steps
- Steps are concrete, actionable instructions a human can follow
- Include setup/precondition info in the sub-category description
Step 3 — Populate tests
Generate test cases covering all four interaction dimensions from PLANS/TESTING.md:
Mouse interactions
- Click, drag, release for every mouse button the feature uses
- Right-click context menus if applicable
- Mouse wheel behaviour
- Hover states and tooltips
- Drag boundaries (what happens at canvas edges, panel edges)
- Double-click behaviour if applicable
Keyboard interactions
- All hotkeys from
CHEATSHEET.md that relate to this feature
- Modifier combinations (Ctrl, Alt, Shift, Ctrl+Alt, Ctrl+Shift)
- Key repeat / held key behaviour
- Escape to cancel
- Enter to confirm
Design considerations
- Multiple zoom levels (1x, 2x, 8x, 16x)
- Different canvas sizes (small 16×16, medium 128×128, large 320×200)
- Multiple layers (1 layer, many layers, hidden layers)
- Grid snap on/off
- Symmetry modes active
- Different brush sizes and shapes
- Different paint modes (normal, custom brush, pattern)
- Edge cases from state diagram guard conditions
Tool-specific GUI / chrome
- Panel visibility toggling
- Panel resizing/docking (if applicable)
- Interaction with other active panels
- Status bar updates
- Toolbar active indicator
State machine edge cases
For each state transition in the diagram that has:
- Guards/conditions: Test both the true and false paths
- Error transitions: Trigger the error condition and verify recovery
- Cancellation paths: Verify clean state reset
- Re-entry: Enter a state, leave, and re-enter — verify no stale state
- Rapid transitions: Quick successive inputs (double-click, fast key repeat)
Undo/redo
- Perform the action, Ctrl+Z to undo, verify canvas state
- Undo then Ctrl+Y to redo, verify canvas state
- Multiple operations then multiple undos
- Undo across tool switches
Step 4 — Announce completion
When the test file is complete, output:
Ready for tests. Created PLANS/TESTS/{NAME}.md with N categories, M sub-categories, and P individual test cases.
The human will then use the qa-test-run skill in separate chat sessions to execute the tests.
