TUI: Test Execution View
Relevant source files
The following files were used as context for generating this wiki page:
- internal/tui/test_executor.go
- README.md
- CONTRIBUTING.md
- internal/agent/tui.go
- internal/tui/onboard/view.go
- internal/tui/onboard-cloud/steps.go
Note: The specific source files for TestTableComponent and LogPanelComponent were not provided in the context. Their functionality is described based on their usage within internal/tui/test_executor.go.
The Test Execution View is an interactive terminal user interface (TUI) for running and monitoring API replay tests. Built with the Bubble Tea framework, it provides real-time feedback on test execution, including progress, status, results, and detailed logs for both the service under test and individual test cases. This view is the default interface when running tusk run in an interactive terminal.
The TUI is designed to be responsive, offering both horizontal and vertical layouts to accommodate different terminal sizes, and provides a rich, navigable interface for inspecting test outcomes and diagnosing failures.
Sources: README.md, internal/tui/test_executor.go:230-232
Architecture
The Test Execution View is orchestrated by the testExecutorModel, which manages the overall state, child components, and the test execution lifecycle. It is composed of several modular components that handle specific parts of the UI.
This diagram shows the main components of the Test Execution View and their relationships.
Sources: internal/tui/test_executor.go:87-94
Core Components
| Component | File | Description |
|---|---|---|
testExecutorModel | test_executor.go | The main Bubble Tea model. Manages state, handles messages, and orchestrates test execution and UI updates. |
TestExecutionHeaderComponent | test_execution_header.go | Displays the header, including the title, progress bar, and summary statistics (total, passed, failed, running). |
TestTableComponent | test_table.go | Renders a navigable table of all tests, showing their status (running, passed, failed, etc.). |
LogPanelComponent | log_panel.go | Displays logs. It can show general service logs or logs specific to the test selected in the TestTableComponent. |
TerminalSizeWarning | terminal_size_warning.go | A component that displays a warning message if the terminal window is too small for the TUI to render properly. |
Sources: internal/tui/test_executor.go:87-94, 252-255
State Management
The TUI operates using two primary state enums to control its behavior and appearance: executionState and viewMode.
| State Type | Enum | Values | Description |
|---|---|---|---|
executionState | stateRunning | The test suite is actively running. | |
stateCompleted | The test suite has finished execution. | ||
viewMode | tableNavigation | The user is navigating the list of tests in the TestTableComponent. | |
logNavigation | The user is scrolling through logs in the LogPanelComponent. | ||
logCopyMode | A full-screen view of the logs, optimized for reading and copying. |
Sources: internal/tui/test_executor.go:28-39
The viewMode determines user input handling and which component is focused. The following diagram illustrates the transitions between view modes.
Execution Flow
The test execution process is driven by a series of asynchronous messages handled by the testExecutorModel's Update function.
Test Loading and Initialization
- The
testExecutorModelis initialized. - If
opts.StartAfterTestsLoadedis true, it dispatches aloadTestsIfNeededcommand. - Upon receiving a
testsLoadedMsg, it populates the test list and starts the execution. - If
opts.StartAfterTestsLoadedis false, it immediately callsstartExecution.
Sources: internal/tui/test_executor.go:300-309, 362-376
Main Execution Loop
The diagram below shows the sequence of messages that drive the test execution for each test.
Environment Grouping and Retries
The test executor includes sophisticated logic for handling different test environments and server crashes.
-
Environment Grouping: Before execution, tests are grouped by their required environment variables, which are extracted from suite-level trace spans. Each group is executed sequentially: the environment is set up, all tests for that group run, and then the environment is torn down before the next group starts.
Sources: internal/tui/test_executor.go:811-837 -
Server Crash & Retry: If a test causes the server to crash, the executor detects this by checking server health. The test that caused the crash, along with any other tests that were running concurrently, are queued for a retry. The executor then attempts to restart the server. After all initial tests in an environment are finished, a "retry phase" is initiated where the queued tests are run again, one by one, to get a definitive result.
Sources: internal/tui/test_executor.go:920-951, 860-886
UI Layout and Navigation
The TUI features a responsive layout that adapts to the terminal width.
- Horizontal Layout (
width >= 100): A two-panel view with the test table on the left and the log panel on the right. This is the optimal layout. - Vertical Layout (
width < 100): A single-column view where the test table is displayed above the log panel.
Sources: internal/tui/test_executor.go:704-710, 755-761
Keybindings
| View Mode | Keys | Action |
|---|---|---|
| Table Navigation | ↑/↓/j/k | Navigate tests |
g / G | Go to top / bottom | |
→ / l | Switch to log navigation | |
q / ctrl+c | Quit | |
| Log Navigation | ↑/↓/j/k | Scroll logs |
g / G | Go to top / bottom | |
y | Copy all logs for the current view to clipboard | |
f | Enter full-screen log view (logCopyMode) | |
← / h / Esc | Switch back to table navigation | |
| Log Copy Mode | f / Esc | Exit full-screen view |
Sources: internal/tui/test_executor.go:642-698
Logging Integration
The TUI captures structured logs (slog) from the application and routes them to the appropriate panel. This is achieved via a custom io.Writer implementation.
This diagram shows how a log message is routed.
The routeLog function inspects the log line for patterns that associate it with an active test. If a match is found, the log is added to that specific test's log buffer in the LogPanelComponent; otherwise, it's treated as a general service log.
Sources: internal/tui/test_executor.go:198-228
Deviation and Cloud CTA
When a test fails with a deviation, the TUI provides detailed information, including a git-style diff for JSON body mismatches. For non-cloud runs, it also displays a call-to-action (CTA) prompting the user to sign up for Tusk Drift Cloud for enhanced root cause analysis.
Sources: internal/tui/test_executorgo:472-506, 137-166
Conclusion
The Test Execution View is a critical feature of the Tusk Drift CLI, providing developers with an immediate, interactive, and detailed overview of their API test suite's performance. Through its component-based architecture, responsive layout, and robust state management, it simplifies the process of running tests and diagnosing regressions by centralizing test status, results, and logs in a single, easy-to-navigate terminal interface. The intelligent handling of environment groups and server crashes further enhances its reliability and utility in a local development workflow.