Testing Mastracode TUI
Guide for interactive testing of mastracode's terminal UI in Konsole.
Devin Secrets Needed
OPENROUTER_API_KEY — for using OpenRouter as a custom provider when Anthropic/OpenAI keys are unavailable
Prerequisites
Build mastracode and its dependencies:
cd /home/ubuntu/repos/mastra
COREPACK_ENABLE_STRICT=0 pnpm build:mastracode
This may take a few minutes. If pnpm has corepack issues, install directly: npm install -g pnpm@10.11.0
If the build fails due to pre-existing DTS errors in @mastra/core or @mastra/memory, use --continue to let downstream packages (including mastracode) still build:
COREPACK_ENABLE_STRICT=0 pnpm turbo build --filter ./mastracode --continue
If unit tests fail with missing @mastra/core/workspace, run pnpm build:core first.
Configuring a Custom Provider (OpenRouter)
If you don't have a direct Anthropic/OpenAI API key, configure OpenRouter as a custom provider:
Edit ~/.local/share/mastracode/settings.json:
{
"customProviders": [
{
"name": "OpenRouter",
"url": "https://openrouter.ai/api/v1",
"apiKey": "<OPENROUTER_API_KEY value>",
"models": ["minimax/minimax-m2.7"]
}
],
"models": {
"activeModelPackId": "custom:Custom",
"modeDefaults": {
"build": "openrouter/minimax/minimax-m2.7",
"plan": "openrouter/minimax/minimax-m2.7",
"fast": "openrouter/minimax/minimax-m2.7"
}
},
"customModelPacks": [
{
"name": "Custom",
"models": {
"build": "openrouter/minimax/minimax-m2.7",
"plan": "openrouter/minimax/minimax-m2.7",
"fast": "openrouter/minimax/minimax-m2.7"
},
"createdAt": "2026-01-01T00:00:00.000Z"
}
]
}
After launching mastracode, you may also need to activate the custom pack via /models → select "Custom" → "Activate".
Verify the status bar at the bottom shows the correct model (e.g., build openrouter/minimax/minimax-m2.7).
Launching Mastracode
cd /home/ubuntu/repos/mastra/mastracode
COREPACK_ENABLE_STRICT=0 pnpm cli
On first launch, mastracode may show a setup wizard. Select "Skip" to proceed to the main TUI without configuring models interactively.
Key TUI Commands
| Command |
Action |
/new |
Create a new empty thread |
/threads |
Open thread selector (↑↓ navigate, Enter select) |
/clone |
Clone current thread |
/models |
Switch model pack |
/help |
Show all available commands |
Programmatic Rendering Tests
For visual/rendering bugs (e.g., border alignment, padding, wrapping), writing a quick tsx script that directly renders the component is more reliable than visual inspection alone:
cd /home/ubuntu/repos/mastra/mastracode
npx tsx test-script.ts
Key approach:
- Import the component directly (e.g.,
UserMessageComponent from ./src/tui/components/user-message.js)
- Render at specific widths and strip ANSI codes to measure visible character widths
- Assert all lines have identical visible width (for bordered components)
- Test at multiple terminal widths (40, 60, 80, 100, 120+) to catch edge cases
- Filter out trailing empty lines from
Spacer components when measuring
- For before/after comparisons, simulate the old logic inline to confirm the bug exists
This approach catches bugs that are hard to see visually and provides concrete pass/fail evidence.
Testing Thread State Isolation
The key scenario for thread state testing:
Generate tasks: Ask the model to use the task_write tool explicitly. Some models (e.g., minimax) may not call it automatically — you may need to say something like: "Please use the task_write tool to create a task list with 3 items: Fix login bug, Add unit tests, Update docs"
Verify tasks visible: Look for the "Tasks [0/N completed]" section with ○/▶/✓ icons between the status line and the editor input.
Test /new: The task progress component should completely disappear. The screen should show only "Ready for new conversation" and an empty input.
Test /threads switch: Switch back to the original thread — messages and tasks should restore correctly.
Test /clone: Cloned threads should start with empty tasks (tasks are ephemeral, not persisted to clones).
Common Issues
- Observational memory errors: You may see errors about
GOOGLE_GENERATIVE_AI_API_KEY for the OM model. Fix this by setting the OM model to an OpenRouter model via /om or in settings.json (models.omModelOverride). Configure the OM model if you expect observation to trigger during testing.
- Model not calling tools: Less capable models may not use mastracode's tool system. Explicitly instruct them to use specific tools by name.
- Status bar shows wrong model: After changing settings.json, you may need to use
/models in the TUI to activate the custom pack.
- Build failures: If
pnpm cli fails with module resolution errors, run pnpm build:mastracode (or with --continue) from the repo root to build all transitive dependencies.
- User message rendering without LLM: The user message box renders immediately on Enter, before any LLM response. You can test rendering bugs without a working LLM connection — just submit a message and inspect the bordered box.
Running Unit Tests
cd /home/ubuntu/repos/mastra
COREPACK_ENABLE_STRICT=0 pnpm --filter mastracode exec vitest run src/tui/__tests__/
Some pre-existing test failures may exist in the broader test suite — focus on tests relevant to the feature being verified.
1---
2name: testing-mastracode-tui
3description: Testing mastracode TUI features interactively in Konsole. Covers model configuration, thread lifecycle, task state isolation, and common blockers.
4metadata:
5 source: https://skillmd.com/skills/mastra-ai/testing-mastracode-tui
6---
7
8# Testing Mastracode TUI
9
10Guide for interactive testing of mastracode's terminal UI in Konsole.
11
12## Devin Secrets Needed
13
14- `OPENROUTER_API_KEY` — for using OpenRouter as a custom provider when Anthropic/OpenAI keys are unavailable
15
16## Prerequisites
17
181. Build mastracode and its dependencies:
19
20 ```bash
21 cd /home/ubuntu/repos/mastra
22 COREPACK_ENABLE_STRICT=0 pnpm build:mastracode
23 ```
24
25 This may take a few minutes. If `pnpm` has corepack issues, install directly: `npm install -g pnpm@10.11.0`
26
272. If the build fails due to pre-existing DTS errors in `@mastra/core` or `@mastra/memory`, use `--continue` to let downstream packages (including mastracode) still build:
28
29 ```bash
30 COREPACK_ENABLE_STRICT=0 pnpm turbo build --filter ./mastracode --continue
31 ```
32
333. If unit tests fail with missing `@mastra/core/workspace`, run `pnpm build:core` first.
34
35## Configuring a Custom Provider (OpenRouter)
36
37If you don't have a direct Anthropic/OpenAI API key, configure OpenRouter as a custom provider:
38
391. Edit `~/.local/share/mastracode/settings.json`:
40
41 ```json
42 {
43 "customProviders": [
44 {
45 "name": "OpenRouter",
46 "url": "https://openrouter.ai/api/v1",
47 "apiKey": "<OPENROUTER_API_KEY value>",
48 "models": ["minimax/minimax-m2.7"]
49 }
50 ],
51 "models": {
52 "activeModelPackId": "custom:Custom",
53 "modeDefaults": {
54 "build": "openrouter/minimax/minimax-m2.7",
55 "plan": "openrouter/minimax/minimax-m2.7",
56 "fast": "openrouter/minimax/minimax-m2.7"
57 }
58 },
59 "customModelPacks": [
60 {
61 "name": "Custom",
62 "models": {
63 "build": "openrouter/minimax/minimax-m2.7",
64 "plan": "openrouter/minimax/minimax-m2.7",
65 "fast": "openrouter/minimax/minimax-m2.7"
66 },
67 "createdAt": "2026-01-01T00:00:00.000Z"
68 }
69 ]
70 }
71 ```
72
732. After launching mastracode, you may also need to activate the custom pack via `/models` → select "Custom" → "Activate".
74
753. Verify the status bar at the bottom shows the correct model (e.g., `build openrouter/minimax/minimax-m2.7`).
76
77## Launching Mastracode
78
79```bash
80cd /home/ubuntu/repos/mastra/mastracode
81COREPACK_ENABLE_STRICT=0 pnpm cli
82```
83
84On first launch, mastracode may show a setup wizard. Select "Skip" to proceed to the main TUI without configuring models interactively.
85
86## Key TUI Commands
87
88| Command | Action |
89| ---------- | ------------------------------------------------ |
90| `/new` | Create a new empty thread |
91| `/threads` | Open thread selector (↑↓ navigate, Enter select) |
92| `/clone` | Clone current thread |
93| `/models` | Switch model pack |
94| `/help` | Show all available commands |
95
96## Programmatic Rendering Tests
97
98For visual/rendering bugs (e.g., border alignment, padding, wrapping), writing a quick `tsx` script that directly renders the component is more reliable than visual inspection alone:
99
100```bash
101cd /home/ubuntu/repos/mastra/mastracode
102npx tsx test-script.ts
103```
104
105Key approach:
106
107- Import the component directly (e.g., `UserMessageComponent` from `./src/tui/components/user-message.js`)
108- Render at specific widths and strip ANSI codes to measure visible character widths
109- Assert all lines have identical visible width (for bordered components)
110- Test at multiple terminal widths (40, 60, 80, 100, 120+) to catch edge cases
111- Filter out trailing empty lines from `Spacer` components when measuring
112- For before/after comparisons, simulate the old logic inline to confirm the bug exists
113
114This approach catches bugs that are hard to see visually and provides concrete pass/fail evidence.
115
116## Testing Thread State Isolation
117
118The key scenario for thread state testing:
119
1201. **Generate tasks**: Ask the model to use the `task_write` tool explicitly. Some models (e.g., minimax) may not call it automatically — you may need to say something like: "Please use the task_write tool to create a task list with 3 items: Fix login bug, Add unit tests, Update docs"
121
1222. **Verify tasks visible**: Look for the "Tasks [0/N completed]" section with ○/▶/✓ icons between the status line and the editor input.
123
1243. **Test `/new`**: The task progress component should completely disappear. The screen should show only "Ready for new conversation" and an empty input.
125
1264. **Test `/threads` switch**: Switch back to the original thread — messages and tasks should restore correctly.
127
1285. **Test `/clone`**: Cloned threads should start with empty tasks (tasks are ephemeral, not persisted to clones).
129
130## Common Issues
131
132- **Observational memory errors**: You may see errors about `GOOGLE_GENERATIVE_AI_API_KEY` for the OM model. Fix this by setting the OM model to an OpenRouter model via `/om` or in settings.json (`models.omModelOverride`). Configure the OM model if you expect observation to trigger during testing.
133- **Model not calling tools**: Less capable models may not use mastracode's tool system. Explicitly instruct them to use specific tools by name.
134- **Status bar shows wrong model**: After changing settings.json, you may need to use `/models` in the TUI to activate the custom pack.
135- **Build failures**: If `pnpm cli` fails with module resolution errors, run `pnpm build:mastracode` (or with `--continue`) from the repo root to build all transitive dependencies.
136- **User message rendering without LLM**: The user message box renders immediately on Enter, before any LLM response. You can test rendering bugs without a working LLM connection — just submit a message and inspect the bordered box.
137
138## Running Unit Tests
139
140```bash
141cd /home/ubuntu/repos/mastra
142COREPACK_ENABLE_STRICT=0 pnpm --filter mastracode exec vitest run src/tui/__tests__/
143```
144
145Some pre-existing test failures may exist in the broader test suite — focus on tests relevant to the feature being verified.