Test Convt Desktop

Test the convt desktop app

crates/convt-app is a GPUI app built on the gpui-kit crate. One process runs per user; a second launch forwards its request to the first over a socket in the runtime directory and exits. The look follows the Paper design (file "convt", page "Desktop app"): Geist and Geist Mono are bundled in crates/convt-app/assets/fonts, the light and dark palettes live in src/ui/theme.rs, and the theme follows the system appearance. Windows:

• The main window (1040x640, title "convt"): a sidebar with Activity, Automations and Settings, plus a trial card in licensed builds. Activity lists running jobs and history in one list, with a defaults bar ("Add files converts right away to Photos → JPEG, Images → PNG, …", Change) and Add files, which converts right away. Photos are HEIC, AVIF, WebP and JPEG; other stills (PNG, SVG, screenshots by name) become PNG. Dropping files on the window does the same. Stop cancels a running job; Retry runs a failed or cancelled one again with the options and output folder it had, which history keeps.
• Quick convert (600x560, title "Convert"): format cards, quality and size options, Codec (H.264 or HEVC, for MP4, MOV and MKV) and Keep audio for video, Background for images (Transparent where the format keeps it, White, Black, or a preset's color; ids background and background-<id>), Save to and File name. A preset sets the controls; Balanced and Original clear what it set. It opens for files sent without a target (convt-app <files>, convt-app open -- <files>, "More options…" in the file manager menus, "Open With Other Application"), for every convt://convert link, and when a request with a target can't run silently (a file that can't be converted, an unknown preset, or a license that stops conversions). Video files show a frame as their thumbnail, here and in Activity (see "Video thumbnails").
• The document pack (src/pack.rs, src/ui/pack.rs, design in docs/document-pack.md): documents (Word, Excel, PowerPoint, OpenDocument, RTF, text, HTML, CSV) need LibreOffice. When nothing can convert a document, Quick convert shows a "Document support isn't installed" card with the pinned size and one Download button instead of format cards; Add files, drops, the popover and a right-click open --to on a document all end up there, and a silent convert never downloads. The card follows the download (progress, Cancel), then the checksum and the install; on success the registry is rebuilt, document targets appear and the target a right-click asked for is picked, but converting still takes Convert. Failures read "Couldn't download document support" (Try again), "The download didn't check out" (checksum) or, for a pack that discovery rejects, "Document support needs reinstalling" with the reason in plain words and the engines' message under it. Settings → General → Documents shows the status, Download, and Remove (asks first, waits for document jobs). A build with no pin (any source build without the CONVT_DOCUMENT_PACK_* variables) says it has nothing to download and offers no button. Status checks are offline; the only network request is the Download click.
• Settings (620x600): General, Presets and License tabs. "Jobs at once" defaults to Auto, shown as "Auto (N)" with N from the CPU count.
• First run (420x420): the Finder step (macOS only), "Start 7-day trial" or "I have a key", and a last step. The last step says photos become JPEG and screenshots and other images become PNG. It shows until the last step is finished, and only in builds that check licenses. Closing mid-setup shows it again. After that, macOS Activity shows a recover card until the Finder extension is on. The Finder step's System Settings picture is a preview (id finder-preview), not a switch.
• The menu bar popover (340x520): drop bar (converts and copies the result to the clipboard), running jobs, automation switches, Open convt and Settings. It opens only from the tray icon, which GPUI can't draw yet, so only tests open it (ui::open_popover). src/tray.rs decides what the icon would show.

Requests come from convt-app [files...], convt-app open [--to <fmt>] [--preset <name>] [--] <files...>, file:// URIs from file managers, convt://convert?file=<path>&to=<fmt> links, convt://activate?key=<key> links (open the License tab with the key filled in, never activate without a click) and convt://auth?state=<state>&code=<code> links (the browser's answer to a desktop sign-in; see "Sign-in and renewal"). A command-line request with --to, or a preset that names a format, converts in place with no window: the output goes next to the original whatever Settings says, no notification is shown and nothing is revealed, and the app quits when the batch is done if nothing else is open. Links never convert without a click.

Licensing: a build from source needs no license and never shows first run or a trial card. With the check on, the sidebar shows the trial card, Quick convert shows why conversions stopped, and the License tab has the key field, Activate and Remove license. convt-app --help prints the usage without opening a window.

Example automation rules live in src/placeholder.rs (screenshots → PNG with copy, screen recordings → MP4, HEIC → JPEG off). Each enabled rule watches one directory, never recursively: macOS screenshots use com.apple.screencapture location (and skip the watch when target is clipboard); recordings use the recording location or Desktop. Tests must set Automation.folder or CONVT_SCREENSHOT_DIR / CONVT_RECORDING_DIR — the poller never opens the real Desktop under cfg(test). Drive it with AppState::poll_automations (twice after writing a file, so the size can settle). A checkbox per rule copies the result; the tray drop bar still copies independently.

Pack tests use TestPacks, a scripted pack::Backend (Fixture::with_packs), never the real one: it counts installs and removes, holds a download mid-way (hold), fails as told (fail_next), and its registry adds TestOffice, a fake document engine, once "installed", so results don't depend on this machine's LibreOffice. Assert packs.installs() == 0 before every click on pack-download; only_the_download_button_reaches_the_installer checks in the source that nothing else reaches install_documents. Ids: pack-card (its label is the title), pack-body, pack-detail, pack-download, pack-cancel, pack-progress, pack-done, and in Settings pack-status, pack-remove, pack-remove-confirm, pack-remove-keep. open_quick records the newest Quick convert window, so window_of::<QuickView> finds what the app opened.

Not testable in the headless tests: the system pickers ("Choose a folder…", Change, Add files' picker) and "Open presets folder"; the tray icon; notifications on a real desktop; how the bundled fonts render (the test platform has no real text shaping). A launched app under Xvfb covers the pickers (through scripts/fake-portal.py), fonts and drag-and-drop; see below.

Sign-in and renewal

Signing in to convt.app is optional and only for Pro (src/account.rs, src/ui/account.rs, the shared client in crates/convt-license/src/account.rs). "Sign in with convt.app" in Settings, License, or the first-run plan step opens <site>/device?state=&challenge=&name=&os=&version= and waits. The site answers with convt://auth?state=...&code=... (or &error=...), which counts only while the app waits with that state; a link the app didn't start, a replay, a cancelled flow's link or one older than 15 minutes is dropped with no network call and a notice. The app trades the code and verifier for a device token, stores {email, token} as account.json next to license.key (or in the credential store), and fetches the Pro key. While signed in, it asks /api/device/license once a UTC day at launch (license_checked in settings.toml) and on Refresh license. Together with the update check below, these are the only network calls the app makes without a click. Ids: sign-in, sign-in-reopen, sign-in-cancel, account-status, account-notice, refresh-license, refresh-status, sign-out, refresh-note, and in General network-updates, network-refresh, network-other.

Tests never reach the network: the Fixture gives the app a scripted TestApi (f.api) that counts exchanges, renewals and sign-outs, so assert f.api.calls() to prove a link or launch called nothing. Fixture::signed_in(cx, key, email) starts signed in. AppState::age_sign_in makes a waiting flow look old. Sign Pro keys with pro_key; read the opened page's state with query(&cx.opened_url().unwrap(), "state") and answer with auth_link.

In a real run, a build from source takes CONVT_ACCOUNT_URL (plain HTTP only to loopback), so point it at the dev server from test-convt-web (for example http://localhost:3001) and set CONVT_LICENSE_PUBKEY to .convt-dev/license.pub so seeded keys verify. Put a fake xdg-open first in PATH that appends its argument to a file: GPUI opens URLs with xdg-open, so that file is how you get the device page URL without a desktop browser. Open that URL in agent-browser (with the real HOME; the app's private HOME has no Chrome), sign in as a fixture, stub HTMLAnchorElement.prototype.click to record the convt://auth link, and click Approve or Cancel. Deliver the link as the desktop file's %U handler would: ./target/debug/convt-app '<link>' with the same environment, which hands it to the running app. Check $CONVT_CONFIG_DIR/account.json, license.key and the devices row (bash scripts/db.sh psql owner). Offline renewal is a relaunch with CONVT_ACCOUNT_URL at a closed port and an older license_checked; revocation is "Sign out <name>" under Macs on the dashboard, then Refresh license. Never xdotool windowkill a GPUI window: it kills the whole app.

Update check

src/update.rs and src/ui/update.rs. While update checks are on (Settings, General, update-checks; on by default) the app fetches the signed manifest at launch once a UTC day (update_checked) and on Check now (check-updates), verifies it with convt-update, keeps the highest accepted update_sequence in settings.toml, and selects the newest build the license covers. It shows update-card in the main window's sidebar ("Update available" with update-download, or "New version" with update-renew) and update-status in Settings. Failures appear only in update-status. Nothing downloads.

Tests give the app a scripted TestReleases (f.releases) that counts fetches; sign manifests with manifest(sequence, &[(version, date)], &update_key()). update_key() must stay different from test_key().

In a real run, a build from source takes CONVT_UPDATE_URL (plain HTTP only to loopback) and CONVT_UPDATE_PUBKEY. Serve a manifest from a temp directory with python3 -m http.server --bind 127.0.0.1 0, signed with a throwaway Ed25519 key outside the repo (payload is base64url JSON; the signature covers convt-update-v1\n followed by the payload text). Manifest build dates may not be later than its issued_at day, and the running build's date is the day it was built, so to show a newer covered build, build a separate binary with CONVT_BUILD_DATE set a few days back in its own CARGO_TARGET_DIR. Use your own license key pair too and pass its public half as CONVT_LICENSE_PUBKEY, so you never need .convt-dev/license.key. To check again the same day, delete update_checked from settings.toml or click Check now.

Headless tests first

crates/convt-app/src/ui/tests.rs opens real windows on GPUI's test platform, clicks elements by id and runs real conversions through default_registry(). They need no display and no permission, so run them for every app change:

cargo test -p convt-app

When adding a test, follow the existing Fixture:

• It points settings, history and presets at a TempDir, so tests never touch the user's config, and calls theme::init.
• Fixture::new is a build from source with no license check. Fixture::licensed(cx, trial_start, key) turns the check on with a test signing key, keeps the trial file and the key file in the TempDir, and never reaches the OS keyring. Sign test keys with license_key.
• It calls cx.executor().allow_parking() before anything else. Conversions run on real job threads; without it the test scheduler panics with "Detected activity on thread ... not deterministic".
• Controls are plain elements built by ui/theme.rs (clickable, primary_button, text_button, switch, checkbox, select, segmented). Each registers its id for test queries; find it with the helpers (click, label, shown). A switch's label is "On" or "Off"; a dropdown's options have the ids {select id}-{option} and only exist while it is open, so click the select first.
• f.main(cx), f.quick(request, cx) and f.settings(tab, cx) open a window at a roomy test size. To test what the app itself opens, call super::route(request, cx) (or show_main, show_settings, open_popover) and get the window with window_of::<View>(cx). Those open at their real sizes; windows_fit_their_content_at_their_opening_sizes checks that the main buttons are not cut off, so extend it when a window grows.
• Silent conversions open no window, so wait on app state with wait_until. Wait on a window's label with wait_for_label. Both poll with a timeout, not a fixed sleep.
• theme::set_dark(true, cx) switches to the dark palette; every_window_renders_in_both_themes opens each window in both.
• Text fields go through theme::field and theme::small_field, never a bare Input: the component sizes its height in rems but pads in pixels, so at convt's 13px rem a bare field cuts off descenders. text_fields_have_room_for_a_whole_line checks the heights. Note that Input::h is the multi-line height; use Styled::h.
• Icons (checkmarks, chevrons) come from ui::assets(), which main.rs registers with with_assets. The test platform draws nothing either way, so the_icons_the_windows_draw_are_bundled checks the asset source instead.
• cx.opened_url() returns the last URL a button opened, cx.read_from_clipboard() what was copied, and cx.shown_system_notifications() the notifications posted (the fixture sets the app identity they need). GPUI's test platform can't reveal files, so in tests AppState::revealed records what would have been revealed.

Request parsing (request.rs) and the single-instance handoff (instance.rs) have plain unit tests in the same crate.

Permission

Launching the app, even under a private Xvfb display, needs the user's explicit permission in the current request. Asking to test, verify or fix the app does not count. Without permission, build it, run cargo test and clippy, and report the visual check as pending with the exact launch steps below. With permission, prefer Xvfb; driving a real desktop session or another person's machine needs that named specifically.

Build

convt-app is excluded from default-members, so cargo build alone skips it.

cargo locate-project --workspace --message-format plain   # must be this checkout
cargo build -p convt-app

On Linux the build needs the GPUI system libraries (xkbcommon, fontconfig, wayland, X11/xcb, vulkan). bash scripts/setup-linux.sh installs them and needs sudo. Without sudo, two gaps are common and can be bridged outside the repo when the runtime libraries are installed:

# fontconfig.pc missing: load fontconfig at runtime instead of linking it.
export RUST_FONTCONFIG_DLOPEN=1
# "unable to find library -lxkbcommon-x11": only the unversioned .so link is missing.
mkdir -p ~/.cache/convt-linklibs
ln -sf /usr/lib/x86_64-linux-gnu/libxkbcommon-x11.so.0 ~/.cache/convt-linklibs/libxkbcommon-x11.so
export LIBRARY_PATH=~/.cache/convt-linklibs

For any other missing library, stop and report it; do not vendor system headers into the repo. macOS needs Xcode with the Metal toolchain (scripts/setup-macos.sh); Windows needs the MSVC build tools (scripts/setup-windows.ps1).

Rebuild after any change under crates/. A Rust-only edit elsewhere in the workspace that convt-app does not depend on can reuse the existing binary.