How to write a test case
What a test case holds in Qably, what makes it good, how to choose its priority and how the cases proposed by Aeris arrive.
A test case describes one behavior of your product: what must be true before, what to do and what must happen. The test code decides whether that behavior still works; the case explains what the test is for, so a person who did not write it can understand a failure.
What a case contains
You fill in these fields when you add or edit a case in a suite. Aeris proposes all of them except the state.
| Field | What to write |
|---|---|
| Title | The behavior, as an active verb plus the expected condition: "rejects an expired token". |
| Objective | What the case verifies, in one sentence. |
| Preconditions | What must already be true before the first step: the account, the data, the configuration. |
| Steps | The actions in order, one per line. |
| Expected result | What the user or the system shows when the steps succeed. |
| Priority | Critical, High, Medium or Low. |
| State | Active, Draft or Deprecated. |
A case is manual or automated. A person runs a manual case and records its result in a manual run. An automated case is linked to a test in your repository, and its results come from the reports your CI sends. Qably treats a case as completely documented when it has a title, an objective, steps and an expected result; preconditions are optional.
What makes a good case
Five habits separate a case that helps from one that only exists:
- One behavior per case. If the title needs an "and", split it in two. It is the same rule as in naming tests.
- Independent. The case sets up its own data and does not depend on another case having run first.
- Explicit data and preconditions. Write the account type, the amount or the date. "A valid user" leaves the reader guessing.
- A verifiable result. State what appears, changes or is returned: "the total shows 90.00", not "it works".
- A title with an active verb. "Rejects an expired token", "applies a discount code". For an automated test, the title starts from the test name, which is also part of the identity of the case.
A weak case and a good one
Both cases below cover the same feature. The weak one can only be run by its author.
| Field | Weak case | Good case |
|---|---|---|
| Title | Login works | Signs in with valid credentials and opens the dashboard |
| Objective | Test login | Verify that a registered user reaches the dashboard after entering the right email and password |
| Preconditions | A user exists | The account ana@example.com exists and is active |
| Steps | Log in | Open the sign-in page; enter the email and the correct password; select Sign in |
| Expected result | It works | The dashboard opens and shows the name of the account |
The good version names its data, lists steps anyone can repeat and has a result that can fail visibly.
Choosing a priority
Priority tells the team what to look at first when several cases fail. These levels are general QA practice, so adjust them to your product:
- Critical: the product becomes unusable, or money, data or access is at risk. For example, signing in, paying, saving an order.
- High: a main feature breaks, but a workaround exists.
- Medium: a secondary feature or a rare path.
- Low: cosmetic details and unlikely combinations.
A quick test: if this case failed on the day of a release, would you stop the release? If so, it is Critical or High. If everything is Critical, nothing stands out.
How cases get into Qably
A case reaches Qably in one of three ways:
- Written by hand. Add a case to a suite and fill in the fields above. It is a manual case.
- Reported by your CI. The first time a report includes a test Qably did not know, it creates a case in the Draft state, with a title taken from the test name and no steps. The suite shows it as Undocumented until it is documented.
- Proposed by Aeris. When a push changes a test file, Aeris, the AI assistant of Qably, reads it in the connected repository and proposes documented cases. Proposals wait in the Review Inbox, and nothing becomes official until a person approves it.
After a push, Aeris only reads the files that match the test file patterns of the project. The defaults are *.spec.ts and *.test.ts; edit them in the Repository view if your tests are named differently.
The Review Inbox shows each proposal with the source code it came from. If a proposal matches an existing case, approving it publishes a new version of that case instead of creating a second case. A proposal without steps cannot be published, and Reject discards one you do not want.
For an automated case that already exists, Document this case asks Aeris to propose its documentation, and the proposal arrives in the same inbox. Once a person changes the title, the steps or the expected result of a case, Aeris leaves it untouched when it documents a suite.
Important: Review a proposal against the requirement, not only against the test code. Aeris describes what a test does; if the test is wrong, an approved proposal publishes that mistake as an official case.
Once you have cases, what kinds of errors to look for helps you find the ones that are missing, and the signals of a case show which ones need work.