Skip to main content
This page describes how calculation tests work underneath and why a green number can be trusted. For how to review a calculation entry in the PRD view, see Reviewing results. Apps that run queries, merge data from multiple sources, and compute scores or totals need a way to show the numbers are right. A chart that renders correctly is not evidence that its values are correct. The approach is the same in every case: control the inputs, assert the exact outputs. A calculation test seeds data small enough that the correct result can be computed by hand, runs the app’s real code over it, and asserts that precise value. Never just that a value appeared.

​
Assert exact values

In the hero test, the seeded world is chosen so the right answer is unambiguous, and the assertion names it:
Three seeded tasks, two completed: the only correct answer is 67%, and the video shows that number on the real dashboard. If the query double-counts, misfilters, or rounds wrong, this fails. A weaker assertion (“a percentage is visible”) passes against any bug. The seed must also include data the calculation should exclude. Most computed values select their inputs with conditions such as a time window, a status, or an owner. A seed containing only qualifying rows can’t catch a broken filter: if a “last 7 days” window silently started counting everything, the number wouldn’t change. So every selecting condition gets at least one seeded row on the wrong side of it (an old completion, the wrong status, another user’s row), with the expected value chosen so wrong inclusion would change the result. The same applies to merged data. When a dashboard combines database rows with numbers fetched from a service, the test seeds the database side, stubs the service side with known values (see Services and workflows), and asserts the merged result the two should produce together.

​
Calculation children: the permutation table

A formula usually has more cases than one video should carry: boundaries, caps, empty inputs, rounding edges. Those become a calculation child under the feature, confirmed by reading a ✓/✗ table rather than watching.
Each check(label, fn) is one row of the table the reviewer reads, so the label is a plain-language claim, bound 1:1 to the assertion inside. Checks are collect-and-continue: every row runs and reports its ✓/✗, then the entry fails if any row failed. The reviewer sees exactly which cases hold, not just the first failure. The division of labor with the hero: the hero proves the value is wired to the screen correctly (one representative case, on camera); the calculation child proves the formula itself across the input space. A calculation test is never used to check that a value shows up in the UI; that is the hero’s job.

​
How the assertions are verified

The obvious way to fake a calculation test is to restate the formula inside the test: compute 67% with the test’s own arithmetic and assert the test agrees with itself. Such a test stays green when the app’s real implementation breaks. The build closes this at several levels:
  • The test must import the app’s implementation. A static gate fails the entry if the test’s imports never leave the prd/ directory. Fixtures don’t count, and neither do direct database queries with the test’s own filters. If the logic lives inline in a component or procedure, it gets extracted into a pure exported function the app itself calls.
  • Every assertion must be computed from it. A second gate analyzes the test’s syntax tree and fails any assertion whose value doesn’t derive from an imported app call, directly (expect(score(9)).toBe(100)) or through intermediate values. Asserting locally computed arithmetic fails the build, as does a conditional with identical branches (x ? 100 : 100) or loading app code dynamically to sidestep the analysis.
  • The calls are recorded at runtime. When the suite runs, every call the test makes into the app’s implementation is captured (function, arguments, and the value it actually returned) and shown in the PRD view’s “App code calls” section, grouped under the check that made them: completionRate(2, 3) → 67. A checks-style test that makes no such calls fails at runtime, and a passing check whose recorded outputs don’t contain its asserted value is flagged for review.
The result: a green calculation entry means the asserted values were computed from the app’s real implementation, and the actual inputs and outputs it produced are visible under each row. What no analysis can settle is whether a derived assertion checks the right property. That stays a review question, and the recorded call sitting next to the claim makes it a quick one.