What goes where
Which file owns which content, system prompt, test files, setup/teardown, rules, and procedures, and how to decide.
AskUI Desktop separates three concerns that are easy to mix up:
- Who the agent is: the system prompt: built-in capabilities, the device prompt, app knowledge, report format, your rules.
- What to do on this run: test files (
tests/): the steps for each scenario. - Shared lifecycle:
setup.md,teardown.md,rules.md: what runs around groups of tests.
Getting this right is what makes a project maintainable: when a run misbehaves, you know which file to open.
| Content | Where |
|---|---|
| Agent identity and error discipline | Built into the app, not editable |
| Facts about the test machine the screen doesn't show | The device profile's Prompt field (devices.json) |
| App knowledge: navigation, state indicators, quirks | tests/ui.md |
| Report structure and status vocabulary | utils/format.md (Extending → Report Format) |
| Standing corrections that override everything | tests/rules.md |
| Behaviour for one suite only | <folder>/rules.md (and <folder>/ui.md for suite-specific app knowledge) |
| Shared preconditions | <folder>/setup.md |
| Shared cleanup | <folder>/teardown.md |
| Reusable step sequences | procedures/<name>.md |
| One test scenario | tests/<name>.md |
The system prompt
Assembled at run start, applies to every test. The parts have different lifecycles, keeping them separate means a change to one never risks the others:
- Capabilities: built in and constant; correct them with rules, not by editing.
- Device prompt: changes per machine; lives on the device profile, so picking a different profile retargets the run.
tests/ui.md: grows as you learn the app; your biggest lever.utils/format.md: typically shared org-wide.tests/rules.md: appended last, takes precedence on conflicts.
What to write in each: Agent behavior.
Test files (tests/)
A test file describes what to do in this specific scenario, nothing else:
- Belongs in a test file: the scenario's steps with expected results, credentials by name, procedure calls.
- Doesn't belong: app knowledge (→
tests/ui.md), device facts (→ the device profile's Prompt), steps every test needs (→ setup/teardown), sequences shared between tests (→ procedures).
How to write the steps themselves: Writing good tests.
Setup, teardown, and rules
Three conventional files per test folder, picked up automatically,
setup cascades outer-first, teardown unwinds in reverse
(details). The one to remember:
when a suite needs different behaviour, add a rules.md in its folder,
project-wide corrections go to tests/rules.md, which changes every test
in the project.
Procedures (procedures/)
A sequence used by more than one test or setup file, called explicitly from a step, fixed in one place (details). Setup/teardown run automatically for a folder; a procedure only runs where a step calls it.
What the agent may do
Keep a run's reach to what the test needs, least-privilege accounts, an opt-in toolbox, scoped tools, secrets, and what belongs in review.
Agent behavior
How to shape the way the agent acts, the built-in error discipline, the device prompt, UI knowledge, the report contract, and rules that win.