Home / Learn

Release v0.4.0

14 Testing

Page 1 of 10

The verifier proves what a contract states, for every input. It cannot tell you whether a cart of two lamps costs 44.70, whether a declined card puts the stock back, or whether a receipt goes out only after the payment. You check those with examples: tests that live next to the code, run against fake services you write in Una, and see every operation the code performs. This chapter writes examples for values, for failures and for effects, and shows where an example ends and a contract begins.

What you'll build

A checkout for a small store. It reserves the units of a cart in the warehouse, charges the customer's card, and mails a receipt. When a step fails, it says why, and puts back what it took. Run against fake services, its log reads:

Output
paid, reference PAY-4470
not enough DESK-02 in stock
the card was declined for 24900 cents
the cart is empty

You will learn to:

  • write an example in every form, with do and the conditions expect takes, and read what una test reports when one fails;
  • test every failure path with expect fails;
  • replace a service with a fake handler installed by given, and check what a call did with expect performed and expect not performed;
  • decide what belongs in a contract and what belongs in an example.

Download this chapter's packages: each step is a package under steps/, and the chapter's program is day-to-day/; run una check . and una run . in one.

Why it works this way

In many languages, tests live in other files, in another framework, with rules of their own. A test can reach the real network or the real clock by accident, so it passes on one machine and fails on the next. Fakes are often made by replacing functions while the program runs, and nothing checks that a fake behaves like the service it replaces. A reader who wants to know what a function is for has to find its tests first.

Una takes a different route:

  1. An example sits next to the code it tests. It is a declaration of the module, checked by una check like any other code, and run by una test.
  2. An example cannot touch the world. It has no host capabilities: every service it needs comes from a handler written in Una, so it gives the same result on every machine.
  3. A fake is an ordinary handler. The checker holds it to the capability's declaration, including the promises of its operations.
  4. Each run records its effects. An example can state which operations the code performed, and which it did not.
Key idea

A contract is proven for every input, before the program runs. An example is checked for one input, when you run una test. State in a contract what must always hold, and write an example for the cases a reader should see and for what the code does to the world.

View the Markdown

Next:14.1 Examples: do and expect