Expected vs actual result: the two lines developers actually read

A developer opens your bug report. They scroll past the title. They skim the steps. Then they stop and read two lines carefully:

Expected: ... Actual: ...

These two lines are where the bug lives. Everything else is context.

If those lines are clear, the developer understands the problem in five seconds. If they are vague, the whole report becomes a conversation instead of a fix.

Short version

Expected = what the software should do, according to a source you can point to.
Actual = what you saw with your own eyes, described exactly.
Both should be one or two short sentences.
Never write "it should work" or "it does not work".
If you cannot say where your "expected" comes from, you may have found a question, not a bug.

What is an expected result?

The expected result is the correct behaviour. It is what the software is supposed to do.

The important part is that it should not be your personal opinion. It should come from a source. When someone asks "who says?", you should have an answer.

Good sources for an expected result, roughly in order of strength:

The requirement or user story — "As a user, I can export up to 12 months of data"
The acceptance criteria on the ticket
The design file — Figma, or a written spec
The API documentation
How the same feature behaves elsewhere in the product
How it behaved before the last release
A common standard — WCAG for accessibility, RFC rules for email addresses
Plain common sense — a total of $0.00 for a paid order is wrong, and no document is needed to say so

If your expected result comes from source 8, that is still fine. Just be aware that opinions can be argued with, and the first six sources cannot.

What is an actual result?

The actual result is what really happened. Just the facts, described precisely.

This is harder than it sounds, because most people summarise instead of describing.

Summary (weak)	Description (strong)
It failed	The page showed "Something went wrong. Please try again." and stayed on the form
Nothing happened	The button showed a loading spinner for 2 seconds, then returned to normal. No record was created
It was wrong	The invoice total showed $0.00 instead of $49.99. The individual line items were correct
The page broke	The page went completely white. The console showed `Uncaught TypeError: t is undefined`

Notice how the strong versions let you picture the screen. That is the test.

Write both, always

The most common mistake is writing only one of them.

If you write only the actual result, the developer has to guess what you wanted. Sometimes they guess wrong and "fix" the wrong thing.

If you write only the expected result, the developer does not know what the failure actually looks like, so they cannot confirm they have fixed it.

You need both, because the bug is the gap between them.

Good and bad examples

Example 1: A form

Bad Expected: The form should work. Actual: It does not work.

Good Expected: After clicking Save changes, the profile is updated and a green "Saved" message appears. Actual: Clicking Save changes shows a spinner for about 2 seconds, then the button returns to normal. No message appears. Reloading the page shows the old values, so nothing was saved.

Example 2: A calculation

Bad Expected: Correct total. Actual: Wrong total.

Good Expected: With a 20% discount on a $62.49 subtotal, the total should be $49.99. Actual: The total shows $0.00. The subtotal and the discount line are both displayed correctly above it.

Example 3: An error message

Bad Expected: Better error message. Actual: Bad error message.

Good Expected: When the password is too short, the form shows "Password must be at least 8 characters" under the password field. Actual: The form shows "Error code 422" at the top of the page. The password field is not highlighted, so the user cannot tell which field is wrong.

Example 4: Something missing

Bad Expected: Photo shows. Actual: No photo.

Good Expected: The uploaded profile photo appears in the header immediately after upload, and stays after a page refresh. Actual: The photo appears immediately after upload, but disappears after a page refresh. The header returns to the default grey avatar. The image file is still listed in the account's media library.

That last detail — "the file is still in the media library" — narrows the bug from "upload is broken" to "the profile link is not being saved". That is a much smaller thing to fix.

Four rules for writing them well

Rule 1: Use numbers, not adjectives

"Slow" is an opinion. "Took 14 seconds" is a fact.

"Too many results" is an opinion. "Returned 847 results, expected 12" is a fact.

Numbers turn arguments into measurements.

Rule 2: Say what did NOT happen too

Sometimes the absence is the bug.

Actual: The record was deleted, but no confirmation dialog appeared first.

Actual: The request failed, but no error message was shown to the user. The failure was only visible in the console.

Silent failures are among the worst bug types, and you have to name the silence explicitly.

Rule 3: Separate what you saw from what you think

Actual: The list shows 0 items. Note (my guess): The API returned data, so this may be a filtering problem in the front end.

Keep the guess clearly labelled and below the facts. A wrong guess mixed into the facts sends people to the wrong file.

Rule 4: Do not describe the fix

Bad expected result: "The code should check for null before reading the amount."

That is a proposed solution, not an expected behaviour. Describe the outcome the user should see, and let the developer decide how to achieve it. They may know a better way, or your suggestion may be impossible.

When "expected" is unclear

Sometimes you genuinely do not know what should happen. The requirement does not cover it. This happens constantly with edge cases.

Do not skip the field. Instead, write it honestly:

Expected: Unclear — the requirement does not say what happens when a user has more than 100 saved addresses. My assumption is that the list should paginate. Needs a decision from the product owner.

This turns your bug report into a useful question. Sometimes the answer is "the current behaviour is correct" and the ticket is closed — which is a good outcome, because now the rule is written down somewhere.

If this happens often on your team, it usually means acceptance criteria are being written too thinly. That is worth raising separately.

Where these two lines sit in the full report

The standard order, top to bottom:

Title
Environment
Preconditions
Steps to reproduce
Expected result
Actual result
Frequency
Evidence — screenshot, video, console log, network requests
Notes and theories

Steps first, then expected, then actual. This order matters because the reader follows your steps mentally, then arrives at the moment of failure exactly where you did.

The evidence section is what proves the actual result. A screenshot showing $0.00 next to your sentence saying "shows $0.00" removes all doubt. Capturing the console and network activity alongside it — automatically, as tools like Crosscheck do — is what turns "actual result" from a claim into a demonstration.

A 30-second check before filing

Read your two lines and ask:

Could a developer who has never used this feature picture both states?
Is my expected result based on something I can point to?
Does my actual result contain at least one specific number, quote, or exact message?
Have I avoided the words "should work", "does not work", "broken", and "wrong"?
Is my guess, if any, clearly labelled as a guess?

Frequently asked questions

Do I need these fields for tiny bugs like typos? For an obvious typo, the title often says everything. But it costs one line, and it removes ambiguity about which spelling is correct.

What if expected and actual are the same but it still feels wrong? Then it is probably not a bug — it may be a usability problem or a design improvement. File it as a suggestion or a usability issue instead. That is still valuable, and labelling it correctly stops it being closed as "works as designed".

Should I quote the requirement in the expected result? Yes, when there is one. Quote the line and link to the ticket. It ends the discussion before it starts.

How detailed should the actual result be? One to three sentences, plus evidence. If you need more, the extra detail probably belongs in a notes section.

What if the actual result changes between attempts? Describe the most common one, then list the variations. Also state how many times each happened. Inconsistency is itself a useful clue.