Skip to content
arula

Stage 03 / 15 minutes / Pairs or individual

Write test specifications

Match each specification claim to evidence that could reveal an incorrect implementation.

Shared intuitionCommon languageEveryday habitsDefine
Output
Test specification
Support
One claim-to-evidence example
Continue when
All readiness checks pass

Repository for this lesson jhipster/jhipster-sample-app-react at 8c9d248 . All source links, commands and observations refer to this pinned revision.

Orient

Why this stage matters

Goal

Explain why write test specifications affects confidence in the build.

Complete when

You can name the decision this stage supports and the risk created by skipping it.

How this supports the lab

This ties the stage to the lab’s central question: Does the evidence show that posting an operation and changing its account balance form one safe, reviewable outcome?

Builds
Shared intuitionCommon languageEveryday habits
Work stage
Define

A 201 response proves that an operation was accepted. It does not prove that the operation and balance changed together, that a retry was harmless or that a rejected request left both records unchanged.

Inputs

Use repository sources and accepted artifacts

Goal

Identify the accepted evidence and artifacts required for this stage.

Complete when

You can explain why each source is relevant and exclude material that does not affect the work.

How this supports the lab

These sources establish what the repository does when operation and balance records can be changed independently. Later claims and tests must trace back to this evidence.

Builds
Shared intuitionCommon languageEveryday habits
Work stage
Define

Change specification

Use only accepted claims and named limitations from stage 2.

Java integration tests

Find available API and repository observations.

src/test/java/io/github/jhipster/sample/web/rest/OperationResourceIT.java

React tests

Inspect the current reducer test surface.

src/main/webapp/app/entities/operation/operation-reducer.spec.ts

Cypress journey

Inspect what a browser test can observe.

src/test/javascript/cypress/e2e/entity/operation.cy.ts

Worked example

Design evidence for atomic rejection

Goal

Study one worked example and identify the judgment behind each step.

Complete when

You can reproduce the reasoning without copying the example’s conclusion.

How this supports the lab

The example models one part of the operation-and-balance problem. You apply the same reasoning to the remaining paths and produce evidence another engineer can review.

Builds
Shared intuitionCommon languageEveryday habits
Work stage
Define
  1. Record the account balance and operation count before the request.
  2. Submit a debit that the specification requires the server to reject.
  3. Assert the response and then observe that neither stored value changed.
Explain the reasoning

The test must fail when either half of the claimed outcome is wrong. Status-only and count-only assertions are too weak.

The worked example covers only the overdraw claim.

Decide

Choose evidence that can disprove each claim

Goal

Separate repository facts from decisions that require human authority.

Complete when

Each question has an accepted answer or remains blocked with a named owner.

How this supports the lab

The repository cannot decide credit, debit, retry, ownership or mutation policy. Those decisions define what balance consistency means and what can be judged safe to ship.

Builds
Shared intuitionCommon languageEveryday habits
Work stage
Define
  • Which claims require Java integration evidence?
  • Which UI claims need a React test or Cypress journey?
  • What state must be observed before and after each request?
  • Which production claims cannot be established with H2?
  • Could a mock or automatic rollback hide the defect?

Use the agent

Use the agent on this repository

Goal

Use the coding agent to support write test specifications while retaining control of decisions and evidence.

Complete when

You verified each response before continuing and carried only accepted findings into the artifact.

How this supports the lab

Bounded prompts help investigate and build the balance change while human checks prevent unsupported agent output from entering the evidence chain.

Builds
Shared intuitionCommon languageEveryday habits
Work stage
Define

These are task patterns for the pinned JHipster source, not answer scripts. Replace every bracketed field with accepted repository work. Open every cited path at the pinned revision and review each response before continuing. If you cannot supply a field, return to the earlier artifact.

Decide before prompting

  • Confirm that the change specification passed its readiness checks.
  • Choose the state observations needed to prove each claim.
01

Map claims to risks

Why this prompt

Tests earn their place by addressing a named failure risk.

For each accepted claim, name the failure risk and the state that must be observed to detect it. Do not propose test code. Identify claims that cannot be observed in the current test environment.
Check before continuing

Reject risks that merely restate the claim. Describe the defect each observation would expose.

02

Design the evidence

Why this prompt

The lowest sufficient test level reduces cost while preserving the required observation.

Draft test-spec rows with claim ID, setup, stimulus, state before, state after, expected result, lowest sufficient test level and evidence limit. Include success, rejection, failure and repeated-request cases when specified.
Check before continuing

Confirm that consistency claims observe both the operation and the account balance.

03

Challenge each test

Why this prompt

A useful test must fail for a plausible broken implementation.

For each test-spec row, describe one broken implementation that could still pass. Flag weak assertions, hidden state and duplicate evidence. Do not revise the rows.
Check before continuing

Strengthen or remove each flagged row and record the reason.

04

Audit evidence limits

Why this prompt

Local H2 results cannot support every production claim.

Audit the revised test specification for claims that exceed its evidence. Pay particular attention to MySQL behavior, concurrency, retries and transaction isolation. State what each test can and cannot prove.
Check before continuing

Carry unresolved production evidence into the release review as a named limit.

Create

Produce the test specification for this repository

Goal

Create a reviewable test specification from accepted inputs.

Complete when

The artifact contains every required field and stays within its stated limit.

How this supports the lab

This artifact records the evidence or decision the next stage needs to move the operation-and-balance change toward a supported release judgment.

Builds
Shared intuitionCommon languageEveryday habits
Work stage
Define
  1. Create one test-specification row for every accepted claim.
  2. Define the setup, stimulus, observations and expected result.
  3. Add success, rejection, retry and failure cases.
  4. Choose the lowest test level that can observe the full claim.
  5. Record each evidence limit, including H2 and concurrency limits.
Artifact structureTest specification

One row per claim. Avoid test code at this stage.

  1. Claim ID
  2. Risk
  3. Setup
  4. Stimulus
  5. Observations
  6. Expected result
  7. Test level
  8. Evidence limit

Challenge

Try to disprove the repository-backed work

Goal

Find a material weakness before the artifact controls later work.

Complete when

Each challenge has evidence, an impact and a recorded response.

How this supports the lab

The challenge tests whether a partial write, duplicate effect, unauthorized operation or unsupported claim could survive the proposed artifact.

Builds
Shared intuitionCommon languageEveryday habits
Work stage
Define
Peer review or self-check

Ask another pair to describe a defective implementation that would pass each test. If you are working alone, remove one state change at a time and ask whether the test would fail.

Required response

The authors strengthen the observations or state why the surviving risk is accepted.

Revise

Use repository evidence before continuing

Goal

Resolve findings and make an explicit decision about readiness.

Complete when

Every readiness check passes, or the work returns to the section that must change.

How this supports the lab

The gate prevents unresolved balance-consistency risks from flowing into code or supporting a stronger shipping claim than the evidence allows.

Builds
Shared intuitionCommon languageEveryday habits
Work stage
Define

Ready to continue when

  • Every accepted claim maps to evidence or an explicit limitation.
  • Success and failure cases observe both the operation and balance.
  • The portfolio includes Java, React and end-to-end evidence only where each level adds a distinct observation.

If a check fails

  • Add the missing state observation instead of adding another status assertion.
  • Move a test to a level that can observe the claim.
  • Narrow any claim that the available environment cannot support.

Transfer

Apply the practice to your work

Goal

Map this practice to a real codebase, role and delivery decision in your work.

Complete when

You can name the equivalent artifact, evidence, owner and next use in your team.

How this supports the lab

The lab succeeds when you can use the same evidence chain to judge an AI-assisted change in a production codebase, beyond this sample’s operation-and-balance problem.

Builds
Shared intuitionCommon languageEveryday habits
Work stage
Define
  • Choose one claim from a service you maintain and name the test level that can disprove it.
  • Identify one green test in your codebase that observes less than its name claims.

Record your answer. The lab is complete only when you can name the equivalent practice, artifact and evidence in your work.