Tester Guidelines (reference)

What the swifter-tester agent reads, and the one surface that exists specifically for it — the project-level .swifter/knowledgebase/. For the overview, the override levers, and the content principles, see Project Guidelines.

The tester is unusual: it has its own free-form guidance folder, and it reads a subset of whichever module's overview/ files apply.

What the tester reads from overview/

On whichever module it's testing, the tester reads 7 of the core overview/ files — STRUCTURE, STACK, ARCHITECTURE, CONVENTIONS, TESTING, INTEGRATIONS, CONCERNS — for stack, layout, and test-strategy context. It does not read PITFALLS.md, CODING_GUIDELINES.md, or any NFR file.

The knowledgebase

A second user-editable surface lives at the project root, separate from the per-module overview/ set:

.swifter/knowledgebase/

A flat folder of free-form markdown holding client-specific testing guidance. The swifter-tester agent globs the folder, reads every file's raw content, and applies what it finds.

Aspect	Detail
Path	.swifter/knowledgebase/ (project-level — not per-module)
File naming	Any markdown file. Glob is .swifter/knowledgebase/*. No required filename.
Schema	None. Free-form markdown; the agent extracts patterns by LLM interpretation.
Created when	Not platform-created; teams add files when they have tester guidance to encode.
Read by	Only swifter-tester, across generate-test-cases, generate-test-scripts, aem-generate-publish-cases. Analyst, developer, architect, default agents do not read it.
Treatment	"MANDATORY to apply if found". Absent → graceful degrade (proceeds without client-specific guidance).

What goes in it (per the tester's README):

• App-area-specific testing prompts.
• Authentication patterns.
• Navigation conventions.

The platform doesn't constrain content; it reads the files and tells the LLM to "extract guidance and patterns". Selector preferences, fixture rules, timing patterns — any topic the team finds useful is fair game.

Decision log is a team convention, not a platform contract. Some teams use the knowledgebase to capture decisions made during work items. That's one shape teams have chosen; the platform asks only for "testing guidance" in any markdown form.

Where guidance is applied

• generate-test-cases — knowledgebase shapes scenario coverage during planning.
• generate-test-scripts — knowledgebase sits alongside live DOM exploration and module specs, but does not override the platform's fixed selector-priority strategy.
• aem-generate-publish-cases — AEM-vertical variant; also consults the knowledgebase.

Selector-priority strategy

When writing scripts, the tester selects locators in this fixed order (knowledgebase guidance informs what to test, not this ordering):

1. Generated locator from live browser exploration (browser_generate_locator) — best
2. data-testid if available
3. Role-based selector with specific identification
4. Text content if unique and stable
5. Combination selectors
6. Stable CSS selectors — last resort