Build one outcome-focused check

1382. Lesson identity

Module

3.15 — Automated QA

Lesson

Build one outcome-focused check

Academic type

Guided Build

Schema type

practical

Order

Lesson 2

Estimated time

50–65 minutes

Capability target

Produce a check with deliberate failure evidence.

1383. Learning objective

After this lesson, you can produce one repeatable automated check that arranges a known state, performs one meaningful action, observes an outcome, and demonstrates that the check fails when the intended behavior is deliberately broken.

1384. Why this matters

A production check is useful only when another developer can run it and interpret its result. A green test with vague setup or weak assertions creates false confidence; a red test with unclear intent creates debugging noise. This check turns an acceptance criterion into an executable piece of evidence. It also gives an AI coding partner a bounded task to implement and review rather than an invitation to generate unverified test code.

1385. Prior knowledge

You should already be able to:

• State an observable acceptance criterion.
• Distinguish a meaningful failure from a test-runner or setup failure.
• Identify the game state and outcome relevant to a small behavior.
• Run the project's existing automated-check command or equivalent validation path.

This lesson builds directly on A test must fail for the right reason.

1386. Core concept

One outcome-focused check should have four deliberate parts:

1. Arrange a known starting state.
2. Act once through the behavior being checked.
3. Observe one bounded, player-relevant outcome.
4. Diagnose the result by confirming that a deliberate defect makes the check fail for the expected reason.

The check is not a transcript of implementation details. It is a repeatable claim about behavior.

1387. Mental model

Use the A-A-O-D check card:

A reliable sequence is:

KNOWN STATE → ONE ACTION → ONE OUTCOME → DELIBERATE BREAK → EXPECTED FAILURE → RESTORE

Keep the check narrow. If it needs several unrelated actions or assertions to prove its point, split the behavior or clarify the acceptance criterion before adding code.

1388. Concrete example

Suppose a small game rule says: when the player collects a valid supply item, the inventory count increases by one.

A focused check can be planned as follows:

• Arrange: Create a player with an empty inventory and place one valid supply item in the collection range.
• Act: Trigger the collection action once.
• Observe: Assert that the inventory count is 1.
• Diagnose: Temporarily change the collection rule so it does not add the item. Run the check and confirm that the failure identifies the expected count assertion rather than a missing fixture, syntax error, or unrelated timeout.
• Restore: Return the rule to its intended behavior and run the check again to confirm it passes.

The assertion is about the inventory outcome. It does not require the check to assert every private method call, animation detail, or internal variable unless those are themselves the contract being tested.

1389. AI-native workflow

Use AI to accelerate implementation and inspection, not to decide whether the check proves the behavior.

1. Write the A-A-O-D check card before asking for code.
2. Give the AI partner the acceptance criterion, the relevant project files or symbols, the existing test command, and the constraints: one behavior, one action, one primary outcome.
3. Ask it to propose the smallest check and to identify any assumptions about fixtures, timing, or runtime state.
4. Inspect the proposal against the card. Reject assertions that only confirm method calls, runner completion, or incidental implementation details.
5. Have the AI partner explain what deliberate defect would make the assertion fail and what failure should appear.
6. Apply or edit the implementation through the project's normal workflow, then run the check yourself.

A useful prompt is:

Implement one automated check for this acceptance criterion: “[observable outcome].” Arrange this starting state: “[state].” Perform only this action: “[action].” Observe only this primary outcome: “[outcome].” Use the existing project test conventions. First list your assumptions and the files you would change. Then show how a deliberate defect would produce an expected assertion failure. Do not add unrelated coverage.

The learner remains responsible for confirming that the deliberate failure is meaningful and that the restored check passes.

1390. Common mistake

The common mistake is to treat a passing runner as proof that the behavior works. A check can pass while never reaching the intended action, asserting only that an object exists, or silently using a fixture that does not represent the claimed starting state. The opposite mistake is to introduce several assertions and setup paths until the check becomes difficult to diagnose. Trace the check through Arrange, Act, Observe, and Diagnose instead.

1391. Guided practice

Build one check for a small behavior already present in the project or in the lesson's practice area.

Step 1: Choose one outcome

Write one sentence in this form:

Given [known starting state], when [one action], then [one observable outcome].

Reject the sentence if the outcome is only “no error occurred,” if it names several unrelated results, or if it cannot be observed through the project's available test boundary.

Step 2: Complete the check card

Record:

• The exact starting state.
• The one action that changes or evaluates the state.
• The primary assertion.
• The likely failure message.
• One deliberate defect that should cause the assertion to fail.

Make one deliberate design decision: choose the narrowest boundary that still proves the player-relevant result. For example, prefer checking the resulting inventory count over checking a private helper call when the acceptance criterion concerns inventory.

Step 3: Implement the smallest check

Use the existing test structure and naming conventions. Keep setup local unless the project already provides a stable fixture. Avoid adding waits, retries, or extra assertions merely to make an unstable check appear reliable. If the behavior cannot be isolated without substantial new infrastructure, document that limitation rather than disguising it with broad setup.

Step 4: Run the check in its intended environment

Capture the initial result and confirm that the check reaches its assertion. If it fails during setup, stop and repair the setup before diagnosing behavior. If it passes, continue to the deliberate-failure phase.

Step 5: Demonstrate deliberate failure

Temporarily introduce one controlled defect in the behavior under test, such as preventing the expected state change. Run only the check. Record:

• The command or test target used.
• The assertion that failed.
• The expected value and observed value.
• Why the failure proves that the check can detect the behavior defect.

Do not keep the deliberate defect. Restore the implementation and run the check again.

1392. Validation / evidence

The work is complete when you can point to all of the following:

• One acceptance criterion expressed as a known state, one action, and one observable outcome.
• A check whose setup, action, and primary assertion can be located without guesswork.
• A passing run after the intended behavior is restored.
• A recorded deliberate-failure run in which the expected assertion fails for the behavior defect, not because of missing setup, a syntax error, or an unrelated environment problem.
• A short diagnosis explaining why the check is repeatable and what it intentionally does not cover.

If the check cannot produce deliberate failure evidence, do not mark it complete. First identify whether the problem is the acceptance criterion, the arrangement, the action boundary, the observation, or the test environment.

1393. Key takeaways

• A production check turns one observable acceptance criterion into repeatable evidence.
• Arrange, Act, Observe, and Diagnose are separate responsibilities; confusing them makes failures harder to interpret.
• One focused outcome is usually more valuable than broad, ambiguous coverage.
• Deliberately breaking the behavior verifies that the check can detect the defect it claims to cover.
• AI can propose and implement the check, but the developer must inspect the assertion and diagnose the failure.

1394. Next lesson

Continue to 3.16 — Debugging.

1395. Knowledge check