QA Test Scenarios — manual scenario writing from a UI

Purpose

Turn whatever the user supplies about a UI — HTML, DOM snapshots, screenshots, component code, a prose description, an old scenario list — into a manual QA scenario document that a tester can copy straight into Notion, Markdown, or a test-management system and execute without further editing. The scenario list is the deliverable; executing or automating it is not.

When to use

• The user asks for QA scenarios, test scenarios, manual test cases, or test coverage.
• The user supplies a page, form, table, modal, dashboard, or admin panel and asks "what should be tested here?".
• The user supplies HTML/DOM/screenshots of one or several related pages and wants scenarios derived from them.
• The user has existing scenarios and asks to improve, rewrite, extend, or deduplicate them.

When NOT to use

• Writing or fixing automated tests → behavioral-testing (unit/integration/API) or e2e-test-authoring (browser automation).
• Finding real defects in an app's source, auditing pages for edge cases or UX gaps → behavior-audit.
• Describing API behavior per endpoint → api-behavior-flow.
• The user asked for design improvements → design-principles / design-validation.

Preconditions

• At least one source of truth about the UI is available (files, screenshots, or a description). If none is supplied, ask for the page before generating — scenarios invented from a product name are worthless.
• Writing scenarios only: do not run tests, launch browsers, start servers, install packages, or edit application or automation code (see the read-only rule in the global AGENTS.md). Reading project files to understand the UI is allowed.

Workflow

1. Inventory the source before writing anything. Read every supplied file in full. Build a list of what the UI actually contains: page/section titles, navigation, buttons, form fields (with required/optional state, input type, placeholder, default value, disabled/read-only state), selects, date pickers, checkboxes, radios, file inputs (accept list, size hint), drag-and-drop zones, rich text editors, tables (columns, row actions), search, filters, sorting, pagination, modals, confirmation dialogs, status indicators, validation messages, and empty/loading states. Record each element's exact visible label — never rename a control.
2. Group multiple files into pages and workflows. When several files or snapshots are given, decide which belong to the same module, which components are shared, and which pages form a Create/Edit/Details trio. Navigation between pages is part of the coverage.
3. Decide coverage per relevant category — include only what the UI actually has: general UI, forms, CRUD, tables, file upload, rich text, negative cases, state and persistence. A static page does not need a CRUD block; a table without pagination does not need a pagination scenario.
4. Draft scenarios in the house style (below), one per line, grouped by page and sub-section (General, Publish Info, Form Actions, …). Keep the sentence action → observable result.
5. Deduplicate. Remove repeats of the same purpose across sections, merge scenarios whose only difference is wording, drop trivial "element is visible" lines that carry no behavior. Keep separately-scoped pairs that genuinely differ (Save creates vs Save Changes updates). Prefer 30 useful scenarios over 100 repetitive ones.
6. Separate confirmed from assumed. Sort every behavior into (a) directly observed in the source, (b) a reasonable behavioral expectation, (c) unverifiable from the source (server-side validation, database persistence, authorization, exact error copy, size limits not declared in the markup). Write (a) and (b) as scenarios; list (c) in a short "Assumptions" note outside the scenario block so the copy-ready text stays clean.
7. Self-review each line against the Validation checklist below, fix, then output.
8. Add value beyond the list only if asked — a one-line note on coverage gaps or unverified areas is welcome, but never interleave explanations between scenarios.

Writing style (the contract)

Every scenario begins with Verify that and states an action plus an observable, testable result.

Verify that clicking the News button opens the Add News modal.
Verify that the Publish Date field displays the selected date correctly.
Verify that selecting a status updates the Status field correctly.
Verify that clicking the Cancel button closes the modal without saving changes.
Verify that clicking the Save Changes button updates the selected news item successfully.

Use simple present tense, correct subject-verb agreement, consistent terminology, and the product's own label names. Keep sentences short.

Rewrite these:

Never write: jargon the tester doesn't need, vague or unfalsifiable expectations, duplicates, invented UI elements, invented features, or error text you did not see.

Coverage reference

• General UI — page load, title and labels, visibility, navigation, component interaction, modal open/close.
• Forms — input handling, required vs optional, valid and invalid values, defaults, field validation, submit, reset, cancel behavior.
• CRUD — create, read, update, delete, confirmation, persistence, correct display.
• Tables — columns, data accuracy, search, filtering, sorting, pagination, row actions, empty state, updated records.
• File upload — selection, drag and drop, supported and unsupported formats, size and dimension limits, replacement, removal, error handling.
• Rich text — input, formatting, headings, lists, links, images, tables, alignment, undo/redo, persistence, RTL and LTR.
• Negative — invalid input, missing required values, unsupported formats, invalid operations, duplicate submission, appropriate error messages.
• State and persistence — saved and updated data, cancelled changes, refresh, status changes, existing values.

Output format

Headings per page or workflow, sub-headings per component group, one scenario per line, no numbering inside a scenario block, no checkboxes, no test-case IDs, no Given/When/Then, no step tables, and no expected-result columns — unless the user asks for them. The block must paste cleanly into Notion or Markdown.

### Add News — Create Modal

General:
Verify that clicking the News button opens the Add News modal.
Verify that the Add News title is displayed correctly.

Publish Info:
Verify that clicking the Publish Date field opens the date picker.
Verify that selecting a date updates the Publish Date field correctly.

Form Actions:
Verify that clicking the Cancel button closes the modal without creating a news item.
Verify that clicking the Save button creates a new news item successfully.

Rules

• Never invent UI functionality. If the source does not show it, it either becomes an explicitly flagged assumption or it does not appear at all.
• Keep the real labels. Rename nothing; a scenario that names a control the tester cannot find is worse than no scenario.
• Create and Edit are not duplicates. They stay separate when the outcome differs.
• Assumptions live outside the scenario block. The copy-ready text stays clean; the caveat goes under a separate heading.
• Ask only when it changes correctness — e.g. two pages plausibly map to different workflows, or a required constraint is unknown and would change several scenarios. Otherwise infer and proceed.
• The output is the only deliverable. Do not start a dev server, run a test suite, or touch application code to "validate" the scenarios.

Common mistakes

• Padding the list with visibility noise ("Verify that the table is displayed") instead of behavior, then dropping the negative cases that actually catch bugs.
• Writing "Verify that the filter works" — name the filter, the trigger, and the observable result.
• Merging Create and Edit into one scenario and losing the Save vs Save Changes distinction.
• Presenting server-side or persistence behavior as confirmed when only client markup was read.
• Padding with file-size, dimension, or authorization scenarios that the source never declares, with no assumption flag.
• Emitting markdown tables, IDs, or Given/When/Then the user never asked for.
• Fixing a UI bug you noticed while writing scenarios instead of reporting it.

Validation

• Every scenario starts with "Verify that" and is a single, grammatically correct, present-tense sentence.
• Every named control, label, column, and status exists in the supplied source.
• Every expected result is observable by a tester.
• No scenario repeats another; Create vs Edit vs Delete outcomes remain distinct.
• Every negative and persistence case that the UI implies is covered.
• Anything not provable from the source is flagged as an assumption outside the scenario block.
• Output is headings + one-scenario-per-line, with no IDs, tables, or checkboxes unless requested.
• Nothing was executed or modified: no test run, browser, server, install, or code edit.