Write good scenarios | Qarmiq docs

A scenario is a promise your product makes, written so that anyone in the company can read it. Everything Qarmiq tells you about stability is measured against that list. If the promises are vague, the verdict is vague. If they are brittle, every redesign breaks them and trust in the results drains away.

For a leader, the scenario list is closer to a risk register than a test suite. It is the one place that says, in plain language, what you are not willing to see break.

Why it matters

If scenarios are…	You get…
Written as test scripts	Results only the QA team can read, and a rewrite after every redesign.
Vague (“everything works”)	A pass that proves nothing and a fail nobody can act on.
Overlapping	The same failure counted several times, and a pass rate that misleads.
Clear promises in plain language	Results you can read in a review meeting without a translator.

What good looks like

A good scenario is one short sentence that a customer or board member would recognise as true. It states what must always hold, not what a user does.

One idea. If it needs “and” to join two promises, it is two scenarios.
A truth, not a journey. “Shoppers should always be able to complete checkout with a valid card”, not “the user logs in, adds to the cart and pays”.
Plain words. No page elements, button colours or steps. A redesign must not make it wrong.
Able to fail. If you cannot describe how it would fail, it is not testable.
Different from the others. Duplicates dilute the signals.

Examples

Good scenario	What it protects
Shoppers should always be able to complete checkout with a valid card.	Revenue.
A signed-out visitor can always reach the login page.	Access and support load.
Only the right email and password ever open an account.	Security and trust.
A shopper should never see another shopper’s order.	Privacy and legal exposure.
The cart should always show the correct total.	Billing disputes.

Common mistakes

Instead of this	Write this	The problem
A user logs in, opens the cart and pays.	Shoppers should always be able to complete checkout with a valid card.	A journey. It describes a path, not a promise.
The user enters abc@test.com and clicks Submit.	A valid email address is always accepted at sign-up.	A single test case. That precision belongs in a check.
Checkout works, sends an email, updates stock and shows a confirmation.	Three scenarios, one for each promise.	A run-on. One failure hides the others.
The search page has a search box and filters.	Search should always return products that match what was typed.	A feature description. It can never fail.
The blue Pay button is bottom right.	A shopper should always be able to pay.	Tied to the design.

Where the detail goes

Keep the scenario short and put the substance beside it:

Checks say what must be true for the promise to be believed. See Write good checks.
Context says what the words mean in your product, what must exist first and what data to use. Example: “Checkout is the page at /checkout with at least one item in the cart. Use the test card with any future expiry. Guests and signed-in shoppers both count.” It is facts and data, not steps.

Never put a password, key or token in a scenario, check or context. Qarmiq refuses text that contains a saved sign-in. Keep sign-ins in Environments.

Who owns what

Role	Owns
Product and engineering leadership	The list of promises: what belongs, what is a red line, what to retire.
QA or test lead	Wording quality, checks and keeping the list free of duplicates.
Engineers	Updating a scenario when the behaviour it describes changes on purpose.

Review the scenario list on a schedule, such as quarterly, the way you would review a risk register. Ask whether it still describes what you would be unwilling to ship broken.

How many

As many as there are things you would be upset to see break, and no more. A few dozen well-chosen scenarios tell you more than hundreds of narrow ones, and are far cheaper to keep true. When two say the same thing, merge them. See Merge and collections.

Give each one an entry point

Set an Entry point, the page or path it applies to, such as /checkout, or / for something site-wide. Write it as your app’s address, not a title. Qarmiq matches entry points to the pages it finds, so consistent paths make Route coverage accurate. See Tags, entry points and collections.

Questions to ask your team

Could I read the whole scenario list in ten minutes and understand what we promise?
Which of these would we stop a release for? Are those red lines?
Does any scenario describe a screen instead of a promise?
What are we not covering that we would be embarrassed to see fail?

A quick test before you accept one

Could a customer or executive agree it is true?
Can you say how it could fail?
Would a redesign leave it unchanged?
Is it different from every scenario you already have?