Tests are part of the spec
You will learn
Why every t27 spec carries its own tests, and what a waveform shows.
In t27 a spec is not finished without its claims: test blocks, invariants and benches live in the same file as the code they check, and the compiler refuses a spec with none. A test can also be run as gates in a simulator. The waves below are a real simulation of Verilog generated from a ternary multiply-accumulate spec, driven by that spec's own test vectors.
Try it
Zoom into one clock cycle and read the values on the buses at a pass mark.

Verilog generated from a ternary MAC spec, driven by the spec's own test vectors under Icarus Verilog: clock, buses, pass marks. Drop a .vcd and it draws yours.
specs/tutorial/07_tests_invariants_benches.t27
// SPDX-License-Identifier: Apache-2.0
; 07 — Tests, invariants and benches
; Lesson 7, and the reason this language exists rather than a header file.
; A spec carries its own claims: examples that must hold, properties that must
; always hold, and the operations worth measuring. All three are emitted into
; every target, so the same claim is checked in Zig, C and Rust alike.
; phi^2 + 1/phi^2 = 3 | TRINITY
module tutorial-07-claims;
pub const TRIT_NEG : i8 = -1;
pub const TRIT_ZERO : i8 = 0;
pub const TRIT_POS : i8 = 1;
pub const TRINITY : i8 = 3;
pub fn trit_add(a: i8, b: i8) i8 {
const sum : i32 = a + b;
const high = if (sum > 1) 1 else sum;
const low = if (high < -1) -1 else high;
return @as(i8, @intCast(low));
}
pub fn trit_mul(a: i8, b: i8) i8 {
return a * b;
}
// ============================================================================
// test — a concrete example
//
// test "name" { ... }
//
// Use it for the cases a reader would ask about: the boundaries, the identity,
// the one that used to be wrong.
// ============================================================================
test "trit_add saturates rather than wrapping" {
try std.testing.expectEqual(@as(i8, TRIT_POS), trit_add(TRIT_POS, TRIT_POS));
try std.testing.expectEqual(@as(i8, TRIT_NEG), trit_add(TRIT_NEG, TRIT_NEG));
}
test "zero is the additive identity" {
try std.testing.expectEqual(@as(i8, TRIT_POS), trit_add(TRIT_POS, TRIT_ZERO));
try std.testing.expectEqual(@as(i8, TRIT_NEG), trit_add(TRIT_ZERO, TRIT_NEG));
}
test "one is the multiplicative identity and zero absorbs" {
try std.testing.expectEqual(@as(i8, TRIT_NEG), trit_mul(TRIT_NEG, TRIT_POS));
try std.testing.expectEqual(@as(i8, TRIT_ZERO), trit_mul(TRIT_ZERO, TRIT_NEG));
}
// ============================================================================
// invariant — a property, not an example
//
// invariant name
// assert EXPRESSION
//
// This is the part a test cannot express. A test says "for these inputs, this
// output"; an invariant says "this holds, full stop". Reach for it whenever a
// claim has no particular input attached to it.
// ============================================================================
invariant trit_set_has_three_states
assert TRIT_POS - TRIT_NEG + 1 == TRINITY
invariant trits_are_ordered
assert TRIT_NEG < TRIT_ZERO
invariant zero_sits_between_the_rails
assert TRIT_ZERO < TRIT_POS
// ============================================================================
// bench — what is worth measuring
//
// bench "name" { ... }
//
// A bench names an operation whose cost matters. It is a declaration of intent
// as much as a measurement: it says this is the hot path.
// ============================================================================
bench "trit_add" {
_ = trit_add(TRIT_POS, TRIT_NEG);
}
bench "trit_mul" {
_ = trit_mul(TRIT_POS, TRIT_NEG);
}
All lessons
Module 1 · The chip
What an FPGA is, which chip we use, and how its pins meet the board.
Module 2 · Numbers in hardware
Bits, trits and number formats, and what arithmetic costs in logic.
Module 3 · Your t27 program
Write a spec, test it, and see why compiling is not the same as being right.
Module 4 · Inside t27c
How the compiler reads a spec and what it writes, including the native t27b.
Module 5 · From spec to hardware
The Verilog t27c writes, the cells it becomes, and what one LUT does.
Module 6 · Reading synthesis
What yosys reports about your design, and which warnings matter.
Module 7 · Place, route, timing
Where the cells land on the die, and whether the clock is met.
Module 8 · The bitstream
How a routed design becomes the bits the chip loads, with no Vivado.
Module 9 · On the board
Ask the chip who it is, load the bits, and check them.