Summary
The project currently has zero automated tests — no test files, no pytest configuration, no CI workflow for tests. The only CI job (docs.yml) deploys MkDocs. For a "Playwright for TUIs" project, this is a significant gap, especially given the concurrency-sensitive async changes in the codebase.
Scope
Test infrastructure
- Add
pytest and pytest-asyncio to dev dependencies
- Create
tests/ directory structure
- Add
conftest.py with shared fixtures (e.g., session launch/teardown)
Unit tests for ScreenSession
_update_buffer() drain loop behavior
get_highlighted_regions() edge cases (empty screen, single color, all highlighted)
get_buffer_display() rendering
get_char_at() bounds checking
get_buffer_line() bounds checking
Tool-level integration tests
launch_tui → send_keys → capture_screen → assert_contains → close_session round trip using example_tui_app.py
- Buffer mode:
launch_tui(mode="buffer") → wait_for_text → find_highlighted → assert_at_position
expect_text finding/timing out
wait_for_text finding/timing out
send_ctrl (Ctrl+C)
Async behavior tests
- Verify
expect_text doesn't block the event loop
- Verify
wait_for_text times out correctly
- Verify
send_keys delay arithmetic
Error path tests
- Invalid session ID
- Closed/missing sessions
- Stream-mode-only tools called on buffer sessions and vice versa
CI workflow
- Add
.github/workflows/test.yml running pytest on Python 3.10, 3.11, 3.12+
Acceptance criteria
pytest runs green locally
- CI workflow runs on push and PR
- Coverage for all MCP tools (at least happy path + one error path each)
Summary
The project currently has zero automated tests — no test files, no pytest configuration, no CI workflow for tests. The only CI job (
docs.yml) deploys MkDocs. For a "Playwright for TUIs" project, this is a significant gap, especially given the concurrency-sensitive async changes in the codebase.Scope
Test infrastructure
pytestandpytest-asyncioto dev dependenciestests/directory structureconftest.pywith shared fixtures (e.g., session launch/teardown)Unit tests for
ScreenSession_update_buffer()drain loop behaviorget_highlighted_regions()edge cases (empty screen, single color, all highlighted)get_buffer_display()renderingget_char_at()bounds checkingget_buffer_line()bounds checkingTool-level integration tests
launch_tui→send_keys→capture_screen→assert_contains→close_sessionround trip usingexample_tui_app.pylaunch_tui(mode="buffer")→wait_for_text→find_highlighted→assert_at_positionexpect_textfinding/timing outwait_for_textfinding/timing outsend_ctrl(Ctrl+C)Async behavior tests
expect_textdoesn't block the event loopwait_for_texttimes out correctlysend_keysdelay arithmeticError path tests
CI workflow
.github/workflows/test.ymlrunning pytest on Python 3.10, 3.11, 3.12+Acceptance criteria
pytestruns green locally