<!-- Tests · Tin · https://tin.ad/docs/learn/tests/ · generated from the built page -->

[Learn](https://tin.ad/docs/learn/) · The language · 14 of 34

# Tests

**Goal.** Write `test` blocks next to your code and run them with `tin test`.

## Your first test

A `test "name" { ... }` block sits in the same file as the code it tests. Run it with
`tin test` instead of `tin run`. A file with only tests doesn't need a `main`.

*first.tin · tin test first.tin*

```tin
fn add(a: int, b: int): int => a + b

test "adding two numbers" {
  assertEq(add(2, 3), 5)
}

test "adding zero changes nothing" {
  assertEq(add(7, 0), 7)
}
```

<!-- output -->
```text
✔ adding two numbers
✔ adding zero changes nothing

2 passed, 0 failed
```

`assertEq(actual, expected)` stops the test if the two values differ. Each test runs in a fresh
copy of the program, so one test can't leave anything behind for the next.

## When a test fails

Here's a test that's wrong on purpose. `tin test` runs the others anyway, and says which assertEq failed, what it
expected and what it got:

*failing.tin · tin test failing.tin*

```tin
fn average(xs: int[]): int => sum(xs) / xs.len

test "average of three" {
  assertEq(average([2, 4, 6]), 4)
}

test "average rounds down" {
  assertEq(average([1, 2]), 2)      // wrong on purpose: integer division gives 1
}
```

<!-- output -->
```text
✔ average of three
✖ average rounds down
    assertEq(average([1, 2]), 2): expected 2, got 1

1 passed, 1 failed
```

On your machine the output is coloured and each line shows how long the test took. The exit code
is 1 when anything fails, so a CI job stops too.

## assertEq and assert

`assertEq` compares any two values of the same type: numbers, arrays, structs, even a
`Result`. `assert` takes a condition and an optional message. Without a message, the
condition's own source code is the message.

*assert.tin · tin test assert.tin*

```tin
fn discount(total: int, percent: int): Result<int, string> {
  if percent < 0 || percent > 100 { return Err("percent must be between 0 and 100") }
  Ok(total - total * percent / 100)
}

test "a quarter off" {
  assertEq(discount(1000, 25), Ok(750))     // assertEq works on any type, even Result
}

test "silly percentages are refused" {
  assert(discount(1000, 150).isErr(), "150% should be refused")
}

test "nothing off" {
  let r = discount(1000, 0)
  assert(r == Ok(1000))                     // without a message, the condition is the message
}
```

<!-- output -->
```text
✔ a quarter off
✔ silly percentages are refused
✔ nothing off

3 passed, 0 failed
```

## Tests next to a program

A file can have a `main` and tests. `tin test` runs the tests:

*beside-main.tin · tin test beside-main.tin*

```tin
type Cart = { items: string[], total: int }

fn add(cart: inout Cart, item: string, price: int) {
  cart.items.push(item)
  cart.total += price
}

test "a cart adds up" {
  var cart = Cart { items: [], total: 0 }
  add(&cart, "tea", 300)
  add(&cart, "cake", 450)
  assertEq(cart.total, 750)
  assertEq(cart.items, ["tea", "cake"])
}

// tin run ignores the test blocks, but still checks that they compile
fn main() {
  var cart = Cart { items: [], total: 0 }
  add(&cart, "tea", 300)
  print(cart)
}
```

<!-- output -->
```text
✔ a cart adds up

1 passed, 0 failed
```

And `tin run` runs `main` and skips them:

*beside-main.tin · tin run beside-main.tin*

<!-- output -->
```text
Cart { items: ["tea"], total: 300 }
```

Skipped doesn't mean unchecked. `tin run` still type-checks every test, so a test can't quietly
go stale when the code changes under it:

*rotted.tin · tin check rotted.tin*

```tin
fn add(a: int, b: int): int => a + b

test "an old test nobody ran" {
  assertEq(add(2, 3, 4), 9)
}

fn main() {
  print(add(2, 3))
}
```

<!-- compiler output -->
```text
error: add takes 2 argument(s), found 3
 --> rotted.tin:4:12
  |
4 |   assertEq(add(2, 3, 4), 9)
  |            ^^^^^^^^^^^^
  = note: signature: add(a: int, b: int)
```

Agents get tests too. In Part 2 you'll test them offline with the mock model, or with a
recorded tape of real model answers.

## Tasks

### Task 1: Leap years

Write `isLeapYear(y: int): bool`, with tests for 2024 (yes), 1900 (no), 2000 (yes) and 2023
(no).

Your answer   Checking needs JavaScript; the solution below works without it.

**Solution

*task-1.solution.tin · tin test task-1.solution.tin*

```tin
fn isLeapYear(y: int): bool => (y % 4 == 0 && y % 100 != 0) || y % 400 == 0

test "every fourth year" { assert(isLeapYear(2024)) }
test "but not every hundredth" { assert(!isLeapYear(1900)) }
test "except every four hundredth" { assert(isLeapYear(2000)) }
test "ordinary years" { assert(!isLeapYear(2023)) }
```

<!-- output -->
```text
✔ every fourth year
✔ but not every hundredth
✔ except every four hundredth
✔ ordinary years

4 passed, 0 failed
```

### Task 2: Fix the average

On an empty array, `sum(xs) / xs.len` stops the program with "division by zero". Change `average` to return
`Option<int>`, and write a test for the empty case.

Your answer   Checking needs JavaScript; the solution below works without it.

**Solution

*task-2.solution.tin · tin test task-2.solution.tin*

```tin
fn average(xs: int[]): Option<int> {
  if xs.isEmpty() { return None }
  Some(sum(xs) / xs.len)
}

test "average of three" {
  assertEq(average([2, 4, 6]), Some(4))
}

test "an empty list has no average" {
  let none: int[] = []
  assertEq(average(none), None)
}
```

<!-- output -->
```text
✔ average of three
✔ an empty list has no average

2 passed, 0 failed
```

## Recap

- A `test` block is code that must not fail.
- `assertEq` shows both sides when it fails.
- Tests live next to the program they test.

In the reference: [Tests](https://tin.ad/docs/ref/language/#tests)
