# UI Testing

> use when **testing Frictionless apps** in Playwright against requirements

- Skill: `tomevault-io/ui-testing` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/ui-testing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/ui-testing/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/ui-testing

---


# UI Testing Skill

Test Frictionless apps in Playwright browser against their requirements.md.

**Goal:** Test and record results only. Do NOT fix bugs during testing — document them in TESTING.md for later resolution.

## Quick Start

All paths below use `{ui_dir}` as a placeholder — get the value from `{cmd} status` (the `base_dir` field).
```
1. Find requirements: {ui_dir}/apps/<app>/requirements.md
2. Check server: `{cmd} status` → get `{ui_dir}` and `{url}`
3. Load app: `{cmd} display("<app>")`
4. Open browser: `{cmd} browser` OR navigate Playwright to {url}/?conserve=true
5. Create TESTING.md from requirements
6. Test each feature, update checklist
7. Document bugs in Known Issues section
```

## Testing Workflow

### 1. Setup

```bash
# Get server info (auto-started)
`{cmd} status`  # → {ui_dir}, {url}

# Load the app
`{cmd} display("<app-name>")`

# Open in Playwright (use url from `{cmd} status`)
`{cmd} browser`  # or navigate to {url}/?conserve=true
```

### 2. Create TESTING.md

Create `{ui_dir}/apps/<app>/TESTING.md` based on requirements.md:

```markdown
# <App Name> Testing Checklist

## Gaps
(Design/code mismatches from `{cmd} audit` - investigate before testing)

## <Feature Category 1>
- [ ] Requirement from requirements.md
- [ ] Another requirement

## <Feature Category 2>
- [ ] More requirements...

## Known Issues
(Bugs found during testing)
```

**Section order:** `## Gaps` must be first (from ui-builder audit), then feature categories, then `## Known Issues` last.

**Checkbox conventions:**
- `[ ]` — untested
- `[✓]` — passed
- `[✗]` — failed

### 3. Test Features

Use Playwright tools to interact with the UI:

| Action | Tool |
|--------|------|
| See current state | `browser_snapshot` |
| Click element | `browser_click(element, ref)` |
| Fill text | `browser_type(element, ref, text)` |
| Fill form | `browser_fill_form(fields)` |
| Check visual | `browser_take_screenshot` |

### 4. Document Results

Update TESTING.md as you test:

```markdown
- [✓] Feature works correctly
- [✗] Feature broken - **BUG: description**
- [ ] Feature not tested yet
```

### 5. Document Bugs

For each bug, document in Known Issues:

```markdown
### N. Bug Title
**Location:** `file.lua:line` or component
**Error:** Error message if any
**Steps to reproduce:**
1. Step one
2. Step two
**Expected:** What should happen
**Actual:** What actually happens
**Root cause:** Analysis of why (if known)
**Impact:** What features are blocked
```

## Playwright Tips

### Getting Element References

Use `browser_snapshot` to get the accessibility tree with refs:
```yaml
- button "+ Add" [ref=e18] [cursor=pointer]
- textbox "Name" [ref=e46]
```

Use the `ref` values in click/type calls.

### Testing Real-time Updates

For features like search filtering, use `slowly: true` in `browser_type` to trigger character-by-character updates:
```
browser_type(element, ref, text, slowly=true)
```

### Checking State vs Visual

- `browser_snapshot` - accessibility tree (state, refs for interaction)
- `browser_take_screenshot` - visual appearance (colors, layout)

Use snapshot for interaction, screenshot to verify visual changes (themes, styling).

## Example TESTING.md

See `{ui_dir}/apps/contacts/TESTING.md` for a complete example with:
- Feature checklists organized by category
- Bug documentation with root cause analysis
- Clear marking of blocked features

## Common Bug Patterns

| Symptom | Likely Cause |
|---------|--------------|
| "attempt to index a non-table object" | Method called with wrong args |
| Changes save when Cancel clicked | Form bound to original, not clone |
| Toggle visual but state unchanged | Property binding not two-way |
| Click handler error | Missing method or wrong `self` reference |

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/zot) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-12 -->