Files
simplex-chat/scripts/ci/ios-sim/README.md
T
Evgeny @ SimpleX Chat ed9e9fe95d mcp, ui: sessions open in the Flat layout, with the avatar on the name line (#8169)
* plan: mcp-flat-sessions

* plan: mcp-flat-sessions, the user's answers

* plan: mcp-flat-sessions, image widths and times per platform

* plan: mcp-flat-sessions, one flat media width and smaller avatars

* plan: mcp-flat-sessions, list breaks

* plan: mcp-flat-sessions, visible avatar gaps and the gap below the sender row

* plan: mcp-flat-sessions, equal gaps around the name

* plan: mcp-flat-sessions, restore the approved gaps

* mcp: open the groups of new sessions in the Flat layout

* ui: avatar on the name line and full-width messages in the flat layout

* ui: record the snapshot references of the flat layout

* ui: flat media beside the go-to button, text below tall name lines

* mcp: source of the session image, Main group check in the e2e test

* plan: mcp-flat-sessions, as implemented

* plans: flat sessions, the tests run on master

* android, desktop: keep the width limit of the media box in intrinsic measurement

* android, desktop: test the intrinsic height of media at an unbounded width

* ui: flat name rows close to their messages, cards at the text edge

* desktop: flat group snapshot references, the media scene

* plans: flat sessions, avatars and flat-layout defects

* desktop: avatar snapshot scenes with photos and placeholders

* ios: flat snapshot references, the deleted items scene

* desktop: avatar snapshot scenes of share, contact and user lists, calls, channel members

* android, desktop: avatars without inner padding, each in its former box

* ios: snapshot scenes of hidden integrity errors in Flat rows and bubbles

* desktop: avatar snapshot references, recorded before the inset removal

* android, desktop: snapshot scenes of hidden integrity errors in Flat rows and bubbles

* ios: hidden integrity errors take no space in the chat

* plans: flat sessions, the user's answers, avatar call sites as implemented, hidden rows

* ios: scenes of the time before deleted items, unread users, appearance

* ios: avatars in Flat rows pass the letters' edge by 2 pt

* ios: 6 pt from the avatar to the message below it in Flat rows

* ios: time on the last line of messages ending with empty lines in Flat

* ios: code cards as wide as the code, the time beside them, in Flat rows

* ios: delivery status only with the time in Flat rows

* ios: time shown on a message before a deleted or hidden item

* ios: no gap below a reactions row between one sender's messages in Flat

* ios: no early wrap of the last word before the time in Flat rows

* ios: name the condition that shows the time before deleted items

* ios: spec links to the moved lines of TerminalItemView

* ios: test of the delivery status without the time in Flat rows

* desktop: snapshot references after the inset removal, hidden integrity error scenes

* android, desktop: blur of blocked members' photos as on iOS

* ios: user picker scene with the chat running, as in the app

* android, desktop: snapshot scenes of the Flat defects and the chat banner

* ios: status without the time only for partial delivery and errors

* ios: snapshot references of the Flat avatar overshoot, gap and defect fixes

* ios: snapshot references without the empty line after a hidden time

* android, desktop: hidden integrity errors take no space; the time before deleted and hidden items

* android, desktop: chat banner 20 dp above its avatar and 10 dp below

* android, desktop: Flat avatars 2 dp past the letters, 6 dp above the text, four layout defects

* android, desktop: share list shows each chat's own avatar

* android, desktop: business, bot and agent placeholders as on iOS

* plans: flat sessions, the decisions as implemented on Android and desktop

* ios: scene of a hidden item between two messages of one sender

* ios: sender name 12 pt after the visible avatar in Flat rows

* ios: rows around hidden items grouped as if the hidden items were absent

* ios: full time in a deleted message bubble

* android, desktop: rows skip hidden items as neighbours; the time before deleted items in Flat rows only

* android, desktop: Flat sender names 12 dp after the avatar

* android, desktop: avatar placeholders from their own assets; unused icons removed

* plans: flat sessions, questions numbered as answered, neighbours of hidden rows, overshoot note

* ios: snapshot references of rows around hidden items and the name start

* android, desktop: hidden rows keep one date separator; marked deleted errors shown; rows rebuilt on the developer setting

* desktop: snapshot references of the Flat decisions, defects, banner and rows around hidden items

* spec, plans: Flat row layout, hidden rows and their neighbours, status with the time; avatar assets as implemented

* android, desktop: new, unread and read statuses only with the time in Flat rows, as on iOS

* desktop: snapshot references of the Flat defects scene with an unread message; plans: partial delivery wording

* mcp: session image with the Flat row geometry: avatar 2 pt past the letters, text 6 pt below it

* mcp: session image with a shorter answer, so the first row shows in full

* ios: user picker snapshot scenes at the height of the sheet

* plans: flat sessions, an avatar column with tighter paddings

* ios: snapshot references of the user picker at the height of the sheet

* plans: flat sessions, the avatar column with only the gap open

* ui: Flat avatar column, the avatar 2 into the padding, text 10 after it

Names, items, later rows of one sender, events and deleted cards sit in the message column; media widths are measured from it. Chats without avatars keep 12 on both sides. The session scene on both platforms; the README image redrawn with the column.

* ui: snapshot references of the Flat avatar column and the session scene

* ui: Flat cards and pills take their corners from the roundness setting

Deleted, marked deleted, moderated, blocked, error and decryption error cards and group invitations: 18 × roundness without a tail, as media, on iOS and Android/desktop. A scene of each platform at roundness 0.3.

* ui: Flat pill text on the text start, sender rows at master's pitch

Deleted, marked deleted, moderated, blocked and error pills start at the message column, so their text lines up with the messages, as on master; in chats without avatars they keep 12 from the screen edge. The name line of a sender row starts at the row gap, as on master; the avatar is centred on it and reaches into the gap above, on both platforms.

* android, desktop: avatars in a box drawn at exactly 5/6 of it, as master's padded placeholders

centeredIn scales its child to 5/6 of the box and centres it with fractional placement, so placeholder edges match master at the pixel at every font scale. Photos and the incognito icon take the same size, up to 1 px larger than master's rounded photo padding. The chat-link thumbnail of the chat list uses the same box, 44 sp.

* android, desktop: avatars in a box at whole pixels, photos fill the drawn box

centeredIn places its child at box/12 rounded down and sizes it to the box less twice that, so placeholders keep master's first and last ink pixel and stay sharp. Photos take their rounded square from the drawn box in pixels.

* ui: photo corners from the nominal size; iOS references of pills, corners and sender rows

The rounded square of a photo keeps its corner radius from the size argument. iOS references for the pill alignment, the corner radius from the roundness setting with a 0.3 scene, and sender rows at master's pitch.

* android, desktop: snapshot references of pills, corners, sender rows and avatars at whole pixels
2026-11-14 22:58:41 +00:00

72 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# iOS app in the simulator on GitHub's runners
`.github/workflows/ios-sim.yml` builds the core library and the iOS app from the branch's code on a macOS runner, starts the app in an iPhone 17 simulator, and drives it through onboarding to the chat list with a scripted smoke test; the app job's smoke test (`images`) then turns off the encryption of local files, creates a group and sends `tests/fixtures/test.jpg` and `logo-large-rgba.png`, each added to the photo library, picked, resized by the core, previewed and sent, and checks the pixel size of each sent file with `sips`. On request it also runs a Claude session that follows a device test plan, and a test backend (relay, directory, names server, contacts) for tests that need servers and peers.
## Running it
The workflow runs only when started by hand, on any branch, from the Actions tab or with `gh workflow run`: [CI on GitHub's runners](../README.md) says how and lists the inputs.
Results: the job logs, the Claude job's summary (Claude's usage) and the artifacts `ios-sim-smoke-test` (a screenshot, a 1000-px view and an accessibility tree per step, the app log, the snapshots in `snapshots/`), `ios-sim-backend-logs` and `ios-sim-claude-test` (the Claude job's smoke test in `smoke-test/`, and per session: `prompt.md`, `report.md`, `shots/`, `transcript.jsonl`, `usage.json`). Read them with `gh run view <id> --log` and `gh run download <id> -n <artifact>`.
## How long it takes, what it costs
- `plan` (ubuntu-24.04, 10 s) reads what the run asks for, names the core library and the backend after their sources, `hashFiles` over the Haskell sources, `cabal.project`, `simplex-chat.cabal` and the build script, and reuses an artifact of the same name that an earlier run of the same branch uploaded (30 days). So every run builds the core library, and the backend when asked, from the branch's own Haskell code, and rebuilds only when those sources change.
- `app` (macOS) first builds what no earlier run built, and uploads it for later runs: `build-core.sh` (30–45 min) builds `lib:simplex-chat` with cabal and the iOS flags, as the Nix iOS build does, into the package `scripts/ios/prepare.sh` expects; `build-backend.sh` (20–45 min, only when asked) builds `simplex-chat`, `simplex-directory-service` and `smp-server`. `prepare-libs.sh` then marks the core library for the simulator (`mac2ios`). The Xcode build takes 8–22 min, the smoke test about 10 min, the snapshots about 18 min more, the backend start about 10 min when asked.
- `claude` (macOS, only when asked, after `app` passed): a new simulator with the app job's build and the smoke test, about 7 min, then the sessions (the smoke plan's took 2.6 min).
A run with reused builds and no extras takes about 25 minutes plus the wait for a macOS runner. Everything but the Claude sessions runs on one macOS runner, so a run waits for one runner, not one per build. Hosted minutes are free for this public repository; the limit is the repository's five concurrent macOS jobs, shared with PR builds (each `build.yml` run takes two), so queue waits can be long. The workflow saves no Actions caches, which this repository evicts within hours and shares with `build.yml`: builds are reused only as the artifacts above, and a core or backend rebuild compiles its dependencies too.
The macOS jobs run on `macos-26`, the image with Xcode 26 and the iPhone 17 simulator; `macos-latest` moves to each new macOS and its Xcode.
## The Claude session
It runs in its own job, `claude`, once the app job has passed: the job installs that job's build (the artifact `ios-sim-app`, kept 14 days) in a new simulator, runs the smoke test to reach the sessions' starting state, adds the plan's images to the photo library (`tests/fixtures/test.jpg`, `tests/fixtures/logo-large-rgba.png`, and a HEIC of the first turned to portrait when `sips` can write HEIC), then one session per layout listed in `claude-scope`, with Claude Code installed from npm at the version the desktop workflow pins too. Only this job references the environment `app-sim-claude`, which holds the secret `CLAUDE_CODE_OAUTH_TOKEN` (a Claude subscription token) and admits the branches its rule allows; one runs per branch at a time. Only the Claude step gets the token, and `claude-test.sh` passes it to the `claude` processes alone. The job checks out without persisting its GitHub token and installs a pinned AXe (`install-axe.sh`), since it holds the Claude token. It starts the test backend when `claude-scope` says `backend: yes`; a run that asks for Claude must then ask for the backend too, or the plan job fails. On master it says `no`, since the smoke plan doesn't use the backend.
Each session's final message ends with `CLAUDE-TEST: PASS`, or `CLAUDE-TEST: FAIL` and the failed cases; the step fails unless every session passes.
- `claude-scope`: whether the cases use the test backend, the model, the layouts, the cases per layout, optional entries per layout, `max-turns` and `max-budget-usd` per session.
- `device-test-plan.md`: the plan (`| ID | Do | Expect |` tables). On master it is a three-case smoke plan; a feature branch replaces it with its own and names its cases in `claude-scope`.
- `claude-prompt.md`: what any session needs to know about the app, the `ui` helper and the test backend; `claude-test.sh` adds the `ui` help, the session's cases, layout, start state and limits, the seeded backend and the plan.
- `claude-guard.py`: a PreToolUse hook that lets through only one plain `ui` command per Bash call, since read-only commands run without asking in every permission mode and Bash inherits the token. Read, Write and Edit are allowed only in the session's own directory, so a session can't change `ui` or the scripts it runs. After each session `claude-test.sh` deletes the session's files, and fails, if the token appears in them or the check for it fails.
- `claude-usage.sh`: each session's turns, duration, tokens and cost "estimated at API prices" (Claude Code's own estimate, not a bill) to the job summary and `claude-usage.json`, or why they are unknown (a session cut short before its token check is not uploaded).
Haiku 5.5 drives the app well: the smoke plan takes a few dozen turns and cents; a 50-case feature plan took 300–450 turns, 30–60 minutes and $1.1–1.7 per session, estimated at API prices. Every run spends the subscription's usage limits, which interactive sessions share.
## Driving the app: `ui`
`ui` wraps AXe (`install-axe.sh`) for scripts and for Claude: tap by label, value or point, long-press, swipe, type, paste, keys, wait for text, find, screenshots with trees, switch the layout (one-hand UI or top bar), relaunch, text size, and the backend's directory (`ui` with no arguments lists them). It needs `SIM_UDID` and `UI_OUT`, which the smoke test exports to the job. Lessons kept in its comments and in the smoke test: text fields have no label (tap them by value), the keyboard capitalizes and autocorrects (compare typed text case-insensitively), the closed user picker is always in the tree, "Cancel" clears the search field and its "Close" image doesn't, the keyboard's keys are below the screen.
## Snapshots: `snapshots.sh`
At the end of the app job's smoke test, `smoke-test.sh` runs `snapshots.sh <derived data> <smoke test dir>/snapshots` when the app it tested lies in the derived data of a build (`…/Build/Products/Debug-iphonesimulator`); the Claude job, which installs the app from a tarball, skips it.
`snapshots.sh` builds the unit-test target `SimpleX Snapshots` (`apps/ios/SimpleX Snapshots/SnapshotTests.swift`, hosted by the app) with `xcodebuild build-for-testing`, then runs it in the smoke test's simulator three times, after `xcrun simctl ui <udid> content_size` `large`, `extra-extra-extra-large` and `accessibility-medium`, and sets `large` back. The test hosts each preview listed in `previewScenes()` (the `previews` of a `PreviewProvider`, in a `VStack`) in a `UIHostingController` in a window of the screen's width and of the larger of two heights, the preview's ideal height and its height in a frame of the screen's size, in the light and dark themes without a wallpaper, ends text editing and removes the running animations, so a text cursor or a spinner is drawn the same in every run, and draws it with `drawHierarchy` at scale 1, one pixel per point. The previews marked `device`, the screens shown in the user guide, are rendered as on the device instead: in a window of the screen's size with the device's safe areas, and with a status bar drawn over them (9:41, full cellular, Wi-Fi and battery icons), so that `scripts/docs/frame-ios-renders.py` places them in the iPhone bezel unchanged. The previews marked `fitting`, sheets that the app sizes to their content (the user picker, in `SheetRepresentable`), are rendered at their ideal height (`fixedSize` vertically), so that flexible rows are not stretched to the screen. The chat item previews (`allSizes`) are rendered at the three sizes, the other previews at `large` only.
`previewScenes()` lists every `PreviewProvider` in `apps/ios` except those in `EXCLUDED` of `apps/ios/SimpleX Snapshots/check-previews.py`, whose renders differ between runs and can be made identical only by a change of the app's code. The iOS job of `build.yml` runs `check-previews.py`, which fails when a `PreviewProvider` is neither listed nor excluded, or when a file has a `#Preview`, since the test renders previews by their type.
The test runs in UTC (`NSTimeZone.default`) and en_US (`-testLanguage en -testRegion US`), so the renders do not depend on the runner's time zone or locale; a preview that shows the current date or time differs between runs, so the previews and the sample contact use `previewDate` (`SimpleXChat/ChatTypes.swift`) in place of the current time. The previews also fix what depends on the build: `SettingsView_Previews` shows version 7.1, and `BadgesSupportSimplexView_Previews` the App Store layout, which `BadgeStore.servedByAppStore` otherwise chooses from the build's receipt. The test sets the environment value `fixedQRCode` (`QRCode.swift`) to the image that `generateImage` draws for a short address link, so every QR code draws this image. The keyboard autocorrects the profile name typed in the smoke test differently between runs, so the test sets the app's current user to the sample user.
The images go to `snapshots/` of the artifact `ios-sim-smoke-test` as 8-bit sRGB PNG files without alpha (`preferredRange = .standard`, `opaque`), named `<preview>-<light|dark>-<size>.png`, with `index-<size>.json` listing each file's scene, theme, size, pixel width and height, scale and the content size category the app saw.
When `apps/ios/SimpleX Snapshots/References` exists, `snapshots.sh` then runs `scripts/ci/snapshots-compare.py <references> <renders> <diff dir>`. It compares each render listed in `index-*.json` with the reference of the same name: a render passes when its file is identical to the reference, or when no channel of any pixel differs from it by more than 8 of 255. A missing or extra render, a changed size or a pixel beyond the tolerance fails: the script writes `compare.json` (each file's result and the failed files) next to the renders and, per failed file, `snapshots-diff/<file>` with the reference, the render and the changed pixels in red side by side, lists the failed files in the job summary and exits with 1, which fails the smoke test step.
`scripts/ci/snapshots-remote.py ios record|check [branch]` renders the snapshots of a pushed branch (the current one by default) on GitHub's runner: it starts `ios-sim.yml` on the branch, waits for the run and downloads `snapshots/` and `snapshots-diff/` of its `ios-sim-smoke-test` to a temporary folder. `record` replaces the PNG files in `apps/ios/SimpleX Snapshots/References` with the run's renders and prints the folder's `git status`, for review and commit; `check` prints the files that failed the run's comparison and the folder of their diff images, and exits with 1 when any failed. It takes the token from `GITHUB_TOKEN` or `GH_TOKEN`, otherwise from `gh auth token`; the token must be allowed to start workflows.
## The test backend
`backend.sh start <backend zip> <work dir>` (with the `backend` input) starts, on the runner, against the preset SMP and XFTP servers:
- a chat relay for channels, and a SimpleX Directory whose address it writes to `<work dir>/directory-link`;
- a CLI peer `ci_admin` that creates, registers and gets approved groups and channels with the profile JSON the app sends: `ci_group` and `ci_channel` ("ci seed"), `ci_cards`, six entries with app-size avatars made by `avatar.swift` ("ci avatar"), a long name, markdown in a description, and `cinews`, `cinews_digest`, `cinews_weekly`;
- a local SMP server with a `[NAMES]` section and `names-resolver.py`, the names `cinews.testing`, `ciboth.testing`, `cialice.testing` and `cibobby.testing` claimed by their owners, and the contacts cialice and Robert, online and accepting connections; its address goes to `<work dir>/names-server`;
- checks before the app starts: a search sent to the directory as a message must list `ci_group` and `ci_channel`, and `/_connect plan` must resolve each name from a fresh peer.
On master's code it starts and passes these checks (the directory answers searches sent as messages); service requests to the directory, which only `f/directory-search` answers, are not checked here.
It writes what it seeded to `<work dir>/seed.md` (the Claude sessions get it) and logs to `<work dir>/*.log`; `stop`, `directory-stop`, `directory-start` and `listings` are its other commands. The app reaches it through the simulator, which shares the runner's network; pointing the app at the names server is a few steps in Settings, described in `claude-prompt.md`.
## Other files
- `use-macos26-sdk.sh`: runner images from 20261013 add Command Line Tools with a macOS 27 SDK that Xcode 26.6's linker can't read; every macOS job points the default SDK back at macOS 26.5. The pinned `macos-26` label runs such an image.
- `earlier-run.sh <artifact name>`: finds the newest run of this branch in this repository with that artifact; artifacts from forks and other branches are never used.