Evaluate SexySpex for executable TermUI specifications

Goal

Evaluate sexy_spex as a way to write executable, Given-When-Then specifications for TermUI behavior.

Research summary

SexySpex is an Elixir BDD framework built on ExUnit. It provides:

• Given-When-Then executable specifications
• Living documentation
• Manual, step-by-step execution
• Error-log detection
• A separate mix spex test command

TermUI already has the lower-level tools that a specification can use:

• TermUI.Test.ComponentHarness to mount components
• TermUI.Test.EventSimulator to create keyboard, mouse, paste, focus, and resize events
• TermUI.Test.TestRenderer to inspect terminal output
• TermUI.Test.Assertions to check text, style, state, and snapshots
• TermUI.Runtime with skip_terminal: true for runtime tests without a real terminal

The likely design is to use SexySpex as the BDD and documentation layer, and use TermUI.Test.* inside each specification step. The Scenic helpers in SexySpex do not apply to TermUI.

Proposed proof of concept

Create one specification for a small interactive component:

1. Given a counter with an initial value of zero.
2. When the user presses the Up key.
3. Then the state changes to one.
4. And the rendered buffer contains Count: 1.

The proof should use ComponentHarness.event_cycle/2, EventSimulator.simulate_key/2, and TermUI render assertions. It must unmount the harness after the scenario.

Integration notes

Suggested test dependency:

{:sexy_spex, "~> 0.2.1", only: :test}

Suggested Mix configuration:

preferred_cli_env: [spex: :test]

SexySpex specifications run with mix spex, not mix test. CI must run both commands if the project keeps its normal ExUnit suite.

Risks and questions

• SexySpex is a small and new dependency with limited adoption.
• The current Hex release is 0.2.1, but parts of its README still show 0.1.0.
• We must decide whether the additional BDD syntax and separate CI path give enough value over descriptive ExUnit tests.
• Start with public component behavior. Do not tie specifications to internal renderer details unless that detail is part of the supported contract.

Acceptance criteria

• Decide whether to adopt, reject, or defer SexySpex.
• If adopted, add the test-only dependency and test environment configuration.
• Add one working TermUI executable specification.
• Check state and rendered output after simulated input.
• Add mix spex to CI.
• Document how executable specifications differ from normal unit tests.
• Record any problems found with cleanup, logs, or test isolation.

References

• https://hex.pm/packages/sexy_spex
• https://github.com/JediLuke/spex
• https://term-ui.hexdocs.pm/09-testing-framework.html
• https://term-ui.hexdocs.pm/02-runtime-internals.html

Start by reading the TermUI.Test.ComponentHarness, EventSimulator, TestRenderer, and Assertions APIs, then review the SexySpex integration and the existing CI configuration. Implement or evaluate the counter specification using ComponentHarness.event_cycle/2 and simulated input, checking state and rendered output. Done means the adoption decision, configuration, CI behavior, documentation, and any cleanup or isolation issues are recorded.