Testing

Companion model

Tests live in dedicated companion files. This is also part of the broader concept simplification strategy: the language keeps one canonical way to find, name, and run tests instead of allowing many unrelated layouts.

• ClassName.lll.ts pairs with ClassName.test.lll.ts
• the test class must be named ClassNameTest
• the test file must side-effect import its host module with import "./ClassName.lll"
• production code must never import .test.lll.ts

@Scenario and testType

Every valid test companion must:

• declare testType as "unit" or "behavioral"
• define at least one static async @Scenario("...") method
• include at least one scenario that directly exercises host-class behavior

Non-decorated static helpers are allowed, but only @Scenario methods are collected by the runner.

Unit vs behavioral

unit scenarios can use direct assertions over logic and data. behavioral scenarios are UI automation only.

Behavioral companions must:

• stay plain companion classes and must not extend anything
• target only the paired production host chosen by filename/class-name convention
• use (subjectFactory: SubjectFactory<Subject>, scenario: ScenarioParameter) for instantiable hosts, or (scenario: ScenarioParameter) for static-only hosts
• act only through user-reachable UI actions and assert only UI-visible outcomes

Behavioral scenarios are required to act through user-reachable UI actions and visible outputs. Hidden internal assertions do not count as behavioral verification.

Browser tunnel requirement

When behavioral tests are discovered, compile mode requires --clientTunnel <url>.

• behavioral tests found without --clientTunnel is a compile error
• tunnel run failure is a compile error
• tunnel pass returns summary output, with fuller output available in verbose mode

If you are using the VS Code plugin, you do not need to set this up yourself. The browser tunnel for behavioral tests is created and managed automatically.

Coverage debt

Coverage is computed over primary files that export classes. A class currently counts as covered when its companion exists and defines at least one static @Scenario.

The tooling emits coverage debt pressure as projects grow.

Fail-safe mode is documented separately because it is intended to grow beyond testing alone.