Skip to content

Desktop native UI testing

Desktop unit and real-backend component tests verify data flow and routing. XCUITest verifies native popovers, windows, and geometry that cannot be reliably proven below the native boundary.

Run macOS UI tests and simulator UI automation sequentially to avoid focus changes dismissing transient popovers. Their builds can run concurrently.

XCUITest must never terminate an already-running Crystal Lattice process. A harness can coexist with the installed app when it uses a separate bundle identifier. Debug and Release builds normally share the app's bundle identifier; use an isolated identifier as in the action-display command below when the installed app is running. If an existing Xcode test or Debug-harness session prevents automation or a new harness launch, stop the run and report that specific conflict to the user; do not terminate it automatically. Do not add forceTerminate, killall, pkill, or equivalent process cleanup to XCTest setup or test scripts.

Deterministic native harnesses are registered through index.js and selected by AppDelegate.mm launch flags. The notification rail harness uses authoritative fake backend snapshots plus the production application and session notification hosts, asserts that the rail pushes message content down, and attaches a screenshot.

The transcript-range harness mounts the production ChatPane with a deterministic 200-message backend. Its focused XCUITest uses the production Show older/newer controls and compares the selected overlapping message's native frame before and after each range replacement:

npm run test:macos-ui:transcript-range

The Connections-panel harness mounts the production panel with deterministic record counts and selects the default or largest current typography preset by semantic name. Its focused XCUITest verifies natural height through three records, bounded scrolling above that threshold, bottom-fade state, and the disclosure control:

npm run test:macos-ui:connections

The action-display harness emits a direct modal response through the production global display owner. Its focused XCUITest opens the native React window, scrolls a 300-line compiled-message body, and verifies reopening with the same display ID and body after both the card's Close button and the native window close button:

npm run test:macos-ui:action-display

To run only the reopening regression alongside an installed app, use this command from the desktop package directory. It gives the harness a separate bundle identifier and build directory:

CLC_ENABLE_ACTION_DISPLAY_HARNESS=1 FORCE_BUNDLING=1 xcodebuild \
  -workspace macos/CrystalLatticeControlDesktopRN.xcworkspace \
  -scheme CrystalLatticeControlDesktopRN-macOS \
  -configuration Debug \
  -destination 'platform=macOS,arch=arm64' \
  -derivedDataPath build/action-display-reopen-derived-data \
  PRODUCT_BUNDLE_IDENTIFIER=com.dynamicprogrammingsolutions.crystallatticecontrol.macos.actiondisplayuitests \
  test \
  -only-testing:CrystalLatticeControlDesktopRN-macOSUITests/ActionDisplayWindowUITests/testLongDirectActionDisplayReopensAfterBothCloseMethods

The desktop-workspace harness mounts the production Home, History, activity rail, and session tab strip with deterministic sessions. Focused methods in ConnectionsPanelUITests verify preview promotion, activity-panel state, request-status accessibility, Home navigation, real Watchlist mouse drag, and real permanent-tab mouse drag. The same harness reports policy-derived sidebar metrics so native tests can verify pointer and arrow-key resizing, bounds, and main-workspace protection without copying dimensions. It also posts a native middle-button click to prove tab close does not select or reorder the tab. MarkdownDisplayMenuUITests verifies that the application Settings item opens the separate keyed Settings window.

The rich-session-UI harness mounts the production ChatPane with portable config-rich model selection plus session-header and composer action controls. Its focused XCUITest verifies native popover selection and placed actions:

npm run test:macos-ui:rich-session-ui

It also mounts the production MessageActionsBar with shared menu-label fixtures from test/fixture/action-menu-labels.json. The compaction label is checked against the real plugin's HTTP schema by the frontend SDK integration test; the longer synthetic label exercises wrapping only. The focused native method testMessageActionNamesWrapAndKeepPinsIndependent checks popup width, row height, pin behavior, dismissal, and attaches a review screenshot. The mobile rich-session-UI Detox suite exercises the same production menu and fixture and saves its screenshot under its artifacts/detox/action-popup-review/. Both tests switch to an oversized action list and prove that the last pin remains reachable by scrolling within the bounded popup. These are native UI checks, not network end-to-end tests.

Harnesses report theme-derived values and measured frames. Native assertions compare those values and relative geometry instead of copying display-preset numbers, allowing preset tuning without rewriting native tests.

Chat operations through HTTP

Run the focused production Chat workflow with:

npm run test:macos-ui:chat-operations

The host runner seeds sessions and a connection in a real temporary backend, then launches the production desktop root with four permanent session tabs. The forwarding HTTP proxy can interrupt send acknowledgement and delay edit acknowledgement while preserving the actual backend response bytes. XCTest drives request/tab eviction and return, main-composer editing, concurrent actions, and recovery Resend/Cancel. It measures native transcript/status frames and wheel movement. The runner applies a command-line bundle identifier override only to its test build, so the installed desktop application can stay open. It checks for an existing instance of that isolated test build and never terminates it. The maintained application identifiers are unchanged.

The Debug bundle and DerivedData are built in build/chat-operations. The runner writes its fixture to build/chat-operations-fixture.json; XCTest resolves that path from its compiled source checkout. The fixture is removed after the run. Direct HTTP inspection verifies the selected message changed and retry did not duplicate the original user payload.