07 · Test Runner

Tests for a handful of pure functions (add, divide, fibonacci, isPalindrome, toSlug), written against the Jest API and run by 3va. You don’t install Jest and you don’t write a config file.

Source: examples/07-testing

Run

cd examples/07-testing
3va test

  ✓ basic arithmetic > add returns the sum
  ✓ basic arithmetic > subtract returns the difference
  ✓ basic arithmetic > multiply returns the product
  ✓ basic arithmetic > divide returns the quotient
  ✓ basic arithmetic > divide by zero throws
  ✓ fibonacci > known values
  ✓ fibonacci > negative input throws
  ✓ isPalindrome > detects palindromes
  ✓ toSlug > converts strings to URL-friendly slugs
  ✓ snapshot testing > math result snapshot

=============================
Tests:   10
Passed:  10
=============================

How it works

• 3va test finds the test files (here math.test.js), runs them, and exits with a non-zero code if anything fails, so it works in CI as-is.
• describe, test, expect and beforeEach are globals. You write import in the test file, and ESM works without a config.
• toBe, toEqual, toThrow, toMatch, toContain, toHaveLength, toBeTruthy, toBeNull and toMatchSnapshot are all used across the examples.

Snapshots

toMatchSnapshot() stores values in __snapshots__/<file>.snap.json, keyed by "describe > test":

{
  "snapshot testing > math result snapshot": "{\n  \"add\": 5,\n  \"multiply\": 20,\n  \"fibonacci\": 21\n}"
}

When the value changes, the test fails and shows both versions:

Failed tests:
  ✗ snapshot testing > math result snapshot
      Snapshot mismatch for "snapshot testing > math result snapshot":
  Stored : { "add": 6, "multiply": 20, "fibonacci": 21 }
  Current: { "add": 5, "multiply": 20, "fibonacci": 21 }
Error: 1 tests failed.

If the change is intended, accept it with 3va test --update-snapshots (-u). Commit the .snap.json files.

Useful flags

3va test tests/unit               # a file or directory
3va test --watch                  # re-run on change
3va test --reporter junit --reporter-file junit.xml   # also: json, tap, dot
3va test --concurrency 4          # max parallel test files (0 = CPU count)
3va test --coverage

=============================== Coverage ================================
  File coverage     :  1/1 files have tests (100.0%)
  Test pass rate    :  10/10 tests passed (100.0%)
  Statement coverage:  24/24 statements executed (100.0%)

  Source file                                        Test file            Tests
  --------------------------------------------------------------------------------
  ✓ ./math.js                                          ./math.test.js       24/24 stmts (100%)

Things to keep in mind

• The snapshot format isn’t Jest’s. 3va writes .snap.json, not Jest’s .snap, so existing Jest snapshot files aren’t reused when you migrate.
• --coverage measures statements, not branches. 3va instruments the project’s sources while the tests run and reports executed statements per file. There’s no branch or function coverage yet, so the number can be higher than what Istanbul/c8 would report for the same code.
• Tests run with permissions too. In a quick check, reading and writing files in the project worked from a test, but process.env was empty and child_process.execSync was denied. 3va test has no --allow-* flags, so grant what tests need in package.json under "3va" (see Permissions).
• Keep the functions under test pure where you can. The React Native, Expo and Tauri examples (11, 12, 13) use exactly that to test app logic without an emulator.