Writing tests — start here
This guide teaches you to write automated tests for a Roku/BrightScript project from scratch. It assumes you have never used Rooibos, BrighterScript, or any BrightScript test tool before. No prior testing experience is required — we define every term the first time it appears.
What is a unit test?
A unit test is a small program that runs one piece of your code with known inputs and checks that it produces the expected output. If the check fails, the test "fails" and tells you what went wrong. Tests let you change code confidently: run them, and if they still pass, you probably didn't break anything.
A trivial example, in plain English:
Given
add(2, 3), I expect the result to be5. If it isn't, fail and show me what I got instead.
That "I expect … to be …" line is called an assertion. A test is mostly a few lines of setup followed by one or more assertions.
The mental model for this project
You write tests once, in Rooibos syntax, and run them two ways:
- Headless is your everyday loop: instant feedback, runs in CI, no hardware. Nearly everything lives here — including
@SGNodenode tests and code coverage (--coverage), all with no device. - Device is the fidelity reference: it runs everything on real hardware, and
--cross-checkdiffs the two lanes so you can trust the fast one. Only behavior that leans on real render-thread timing needs it.
The same file works in both. You write one kind of test; the rare one that genuinely needs hardware you mark @deviceOnly, and the fast lanes skip it.
Vocabulary you'll see
| Term | Meaning |
|---|---|
| Assertion | A check like m.assertEqual(actual, expected). A failed assertion fails the test. |
Test (@it) | One scenario with a name and some assertions. |
Group (@describe) | A named bunch of related tests. |
Suite (@suite) | A class holding groups and tests, usually one per file. |
| Spec file | A *.spec.bs file containing one or more suites. |
| Fixture / setup | Data or state prepared before a test runs. |
| Test double | A stand-in for a real dependency — a mock, stub, or spy. |
| Headless | Running without a Roku device (on a simulator in Node). |
How this guide is organized
Read in order the first time; later, use it as a reference.
- Your first test — set up a project and watch a test pass, then fail, then pass.
- Anatomy of a test file — every line of a spec, explained.
- Assertions — the full checklist of
m.assert*methods. - Organizing tests — suites, groups, and file layout.
- Parameterized tests — run one test over many inputs.
- Setup & teardown — shared fixtures and cleanup.
- Mocks, stubs & spies — isolating the unit under test.
- SceneGraph & async tests — testing nodes (they run headless).
- Headless vs device — what runs where, and designing for it.
- Cookbook — copy-paste recipes for common situations.
- Common mistakes — the errors everyone hits, and their fixes.
Prerequisites
You need brighttest installed and a project set up. If you haven't done that, do the Quick start first (about five minutes), then come back here.