Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 36 additions & 0 deletions docs/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,42 @@

The gates a change has to pass, and the drivers that prove the window works. Setup is in the [README](../README.md).

## Backend v0.8.0 compatibility

The submodule pins `3259f8b`, the upstream `v0.8.0` release.
The bridge uses policy-audited model-list decoding and Bedrock's per-model names and
context windows. Trust maps are rooted in the session project. Resuming a terminal
session preserves its saved side conversations and rewind checkpoints.
The UI does not yet present fetch-host, language-server, or manifest-plan approvals;
those new requests are refused without consuming another pending approval.

## Current regression checks

- `npm run build`: bridge and secure-file helper builds, TypeScript, and Electron bundles.
- After building, `node --test scripts/*.test.mjs`: renderer state, models, file access,
memory retention, avatar motion and traits. File tests use the actual secure-file helper.
- `cargo test --all` and `cargo clippy --all-targets --all-features -- -D warnings`: bridge
and secure-file helper gates, including deterministic parent-directory replacement attacks.
- After building, `node scripts/drive-ux-acceptance.mjs`, `node scripts/drive-bot-history.mjs`,
and `node scripts/drive-models.mjs`: isolated Electron acceptance checks with deterministic
provider replies. These cover the current tab layout, search, history, drafts, approvals,
memory, and model selection. Command approvals include the resolved execution plan and
files written by redirections.
- `node scripts/drive-secure-files.mjs`: real preview and memory IPC, symlink rejection,
edit conflicts, history deletion and bot recreation, without model calls. To verify packaging,
build with `node scripts/package.mjs`, then set `SECURE_FILES_APP` to the packaged executable
when running the same driver. Both `bravebot-rpc` and `bravebot-ui-files` must ship in Resources.
- For a submodule update, also run
`cargo test --manifest-path vendor/bravebot/Cargo.toml --target-dir target --all --locked`.
On Apple Silicon with an Intel Rust toolchain, add `--target aarch64-apple-darwin`
and `--config 'target.aarch64-apple-darwin.runner=["/usr/bin/arch","-arm64"]'`
(install the target with `rustup target add aarch64-apple-darwin`). The upstream confinement tests
need native subprocesses: translated binaries can fail with `Failed to open libRosettaRuntime`.

The session-store and confinement tests need filesystem and subprocess access outside the
Codex sandbox. A missing temporary session record under that sandbox is not a passing test;
rerun with the required access.

The Rust side has eight integration suites under `crates/bravebot-bridge/tests/` — the protocol
projections, dispatch, the layering rules the crate docs describe, and the refusal
guarantees that the security model rests on.
Expand Down
103 changes: 103 additions & 0 deletions docs/ui-ux-redesign.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
# UI and UX implementation audit

Branch: `codex/ui-ux-redesign`

The full review is the scope. Runtime checks use the actual Electron application and isolated test projects.
Compilation, interaction assertions, screenshots, and live-agent checks provide
complementary evidence; their boundaries are recorded below.

## Requirements and evidence

- [x] 1. Persist per-session drafts and scroll; background sessions; visible run,
approval, completion and failure states; safe explicit stopping.
- [x] 2. Actionable errors with diagnostic details and safe recovery actions.
- [x] 3. Growing composer, secondary toolbar, header export, keyboard hints,
drafting during runs, explicit queue, persistent Stop.
- [x] 4. Conversation-first widths, responsive inspector drawer, focus mode,
softer message colors and retained avatars.
- [x] 5. Overview / Changes / Files inspector; compact empties; persistent
pending decisions; event navigation; accurate trust distinctions.
- [x] 6. Near-bottom follow, new-activity button, approval navigation,
reduced-motion scrolling and retained reading position.
- [x] 7. Approval summaries, readable expandable diffs, visible permission scope,
revocation controls, separate approval and application outcomes.
- [x] 8. Bot overview and conversation history; continue/new actions; bot badges;
titles and status; search; session pin/archive and discoverable menus.
- [x] 9. Wider bot editor; project explanation/duplication; readable/raw memory,
update history, deliberate edit/reset; persistent-memory explanation.
- [x] 10. Copy/wrap code; conversation search; project-wide filename search;
preview/open-in-editor; validated local references; explicit file attachments.
- [x] 11. Typography, contrast, density, hit targets, composer name, status
announcements, modal focus containment/restoration, keyboard verification.
- [x] 12. Welcome actions and recent projects; first-project guidance; backend
readiness/diagnostics; recent models; app-supported capabilities and context limits.

## Acceptance evidence

The Electron driver is `scripts/drive-ux-acceptance.mjs`. It launches the production
build with a fresh user-data directory and disposable project. It records 41
screenshots and fails on assertion failures or renderer exceptions. Screenshots
were opened and visually inspected, including the final dark scrollbar and
memory-reset confirmation refinements.

| Requirement | Visual evidence (screenshot prefixes) | Functional evidence |
| --- | --- | --- |
| 1. Conversation continuity | 02, 14–16, 40 | Independent drafts across switching and reload; background question remains reachable; Stop invalidates pending question; queue remains paused until Resume; failed first turn remains one sidebar row even with a stale session list. Native restart also retained a draft. |
| 2. Error recovery | 15, 17, 35–36, 38, 40 | Cancellation, rate-limit and authentication states; continuation appends to an existing draft and does not resend actions; setup help and diagnostics open; readiness can be checked again. |
| 3. Composer | 02, 10, 13, 15, 17, 37 | Growing multiline input; draft while busy; queue, Stop and Resume; attachments; header Export; keyboard hints. Queue waits across both the start and completion of automatic memory maintenance. |
| 4. Layout and identity | 02–04, 19, 26–27 | Focus hides sidebars and restores their prior state; reading width stays bounded; 950 px window uses an inspector overlay; comfortable/compact density; light/dark colors and avatars. |
| 5. Inspector | 02, 29–32 | Overview, Changes and Files; compact empties; pending write visible; one normalized path despite a reference-backed tool target; applied state follows the tool outcome. |
| 6. Reading position | 33–34 | Incoming events preserve scroll position while reading; switching restores it; New activity returns to the bottom; reduced-motion preference exercised. |
| 7. Approvals and grants | 05–06, 28–31 | Trusted parent path, untrusted exception and exact command scope; revoke both grant types; expanded numbered diff; waiting → applying → applied distinct from the approval decision. Native backend also applied a reviewed disposable-file update. |
| 8. Bots and sessions | 14, 18–19, 39–41 | Pin, archive and restore; bot conversation history; Continue and New; badges/status; duplicate appears as a separate bot in its chosen project. Search controls inspected. |
| 9. Memory/editor | 20–25, 41 | Real main-process storage: edit → save → readable/raw → explicit reset → revision review → restore → save. Project remains fixed; duplication creates a new bot. Reset confirmation scrolls clear of the sticky footer. |
| 10. Content tools | 07–10, 32 | Conversation search, copy to clipboard, code wrap, local-reference preview, default-app dispatch, attachment selection/removal, filename search. Real file boundary/search/attachment validation covered by regression tests and native file search/preview. |
| 11. Accessibility | 03–08, 20, 23, 27 | Modal Tab wrapping, Escape and launcher-focus restoration; input names; visible focus; density; semantic status/alerts; readable accent text; built-in accent/message foreground contrast tests. |
| 12. Onboarding/models | 01, 11–12, 35–36, 38–39 | Welcome/recent projects; project trust choice; disabled send with missing backend; Check again; model selection, Recent ordering, context windows and only app-supported capability badges. |

## Verification boundaries

The deterministic driver replaces provider/bridge replies and native file-picker
answers, including permission-list fixtures and the default-app dispatch endpoint.
It uses the real renderer, preload IPC, experience persistence, bot definitions,
and memory/history file operations. It does not spend tokens with a provider or
alter a user's project. These fixtures verify UI state and interaction behavior;
they do not claim a new live-provider integration run for every screenshot.

Earlier native tests exercised the actual backend: an unanswered question remained
active in a background conversation; answering it sent the queued follow-up; Stop
woke a pending request without approval; an explicitly resumed queue completed;
and a reviewed untrusted patch changed only the disposable sample file. Native
search found an unopened source path and previewed its contents. The draft survived
an application quit/relaunch. Inconsistent native captures were discarded and the
remaining visual work was completed with the authorized Electron driver.

## Fixes found during acceptance

- Cancellation now wakes a waiting confirmer; reused request IDs cannot rewrite
answers or approvals from earlier turns.
- Failed first turns migrate to their durable ID without losing their sidebar row.
- Reference-backed writes and approval paths produce one Changes row.
- Queued work stays paused after Stop/error, but a new explicit task with no old
queue does not inherit a stale pause. Automatic bot memory maintenance reserves
the session until its completion announcement releases the queue.
- Recovery preserves an existing draft and asks to review current project state
before continuing, rather than automatically repeating writes or commands.
- Dialog focus, sticky editor controls, readable memory headings, reset visibility,
primary-button styling, text accent contrast and dark scrollbars were corrected
against screenshots. Empty archives have a direct, useful explanation.

## Checks and reproduction

- `npm run build`: passed (TypeScript, bridge, main, preload and renderer).
- `node --test scripts/ux-state.test.mjs scripts/bot-model.test.mjs`: 14 passed.
- `cargo test -p bravebot-bridge`: 87 passed during this implementation.
- `cargo clippy --all-targets --all-features -- -D warnings`: passed.
- `node scripts/drive-ux-acceptance.mjs`: full acceptance run passed.
- `git diff --check`: passed.

Build before running the driver. GUI execution needs permission outside the
sandbox on macOS. By default screenshots go to `/private/tmp/bravebot-ux-final`;
set `UX_OUTPUT` to choose a different evidence directory. Provider credentials
remain a deployment/environment requirement, and the setup UI describes that
boundary without exposing credentials.
16 changes: 16 additions & 0 deletions scripts/drive-bot-history.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,22 @@ try {
await overview();await page.locator('.bot-conversations button').filter({hasText:'Review the sample project'}).click();
await page.getByText('Review the project and show a code example.',{exact:true}).waitFor();
await snap('03-open-archived-conversation');
await page.getByRole('tab',{name:'Files',exact:true}).click();
assert.equal(await page.locator('#panel-files .panel-head').count(),0);
assert.equal(await page.getByRole('searchbox',{name:'Search project files by name'}).count(),0);
const panel=await page.locator('.context').boundingBox();
const tree=await page.locator('.tree-body').boundingBox();
assert.ok(Math.abs(panel.y+panel.height-tree.y-tree.height-14)<2,'File list fills panel height');
await snap('03-files-full-height');
await page.getByRole('button',{name:'Search files',exact:true}).click();
const fileSearch=page.getByRole('searchbox',{name:'Search project files by name'});
await fileSearch.fill('sample');
await page.locator('.file-search-results button').filter({hasText:'src/nested/sample.txt'}).waitFor();
await snap('03-files-search');
await fileSearch.press('Escape');
assert.equal(await fileSearch.count(),0);
assert.equal(await page.getByRole('button',{name:'Search files',exact:true}).evaluate(el=>el===document.activeElement),true);

await overview();await page.getByRole('button',{name:'New conversation',exact:true}).click();
await page.getByRole('button',{name:"Don't trust",exact:true}).click();await page.getByRole('dialog').waitFor({state:'hidden'});
await page.getByRole('textbox',{name:'Message the agent'}).fill('Keep this newer conversation draft');
Expand Down
2 changes: 1 addition & 1 deletion scripts/drive-models.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ try {

await trigger.click()
await page.getByRole('option', { name: /Claude Sonnet/ }).waitFor()
assert.deepEqual(await page.getByRole('option', { name: /Claude Sonnet/ }).locator('.model-capability').allTextContents(), ['Text', 'Vision', 'Tools', 'Reasoning'])
assert.deepEqual(await page.getByRole('option', { name: /Claude Sonnet/ }).locator('.model-capability').allTextContents(), ['Text', 'Tools'])
assert.equal(await page.getByRole('option', { name: /Brave model/ }).locator('.model-capability').count(), 0)
const search = page.getByRole('combobox', { name: 'Search models' })
await search.fill('VISION')
Expand Down
Loading
Loading