Skip to content

Record your screen, ship a demo. Free and open-source, GPU-accelerated, no watermarks, no subscriptions. Windows, macOS, Linux. Actively maintained.

docs: prevent incorrect assumptions about CI coverage

shaun09273066a50ce06c
diff --git a/.harness/docs/git-workflow.md b/.harness/docs/git-workflow.md
index 1e67d6428..e522df3ca 100644
--- a/.harness/docs/git-workflow.md
+++ b/.harness/docs/git-workflow.md
@@ -21,7 +21,7 @@ Conventions for the Mavis reins when working in this repo.
## CI (`.github/workflows/ci.yml`)
-CI runs on every PR to `main`, `feat/ai-edition` and `release/**`, and on every push to those:
+CI runs on every PR to `main`, `feat/ai-edition`, `release/**` and `integration/**`, and on every push to those:
- `npm run lint` (Biome)
- `npx tsc --noEmit` (TypeScript, app code)
- `npx tsc -p tsconfig.test.json --noEmit` (TypeScript, test files — a separate gate at zero)
@@ -29,8 +29,9 @@ CI runs on every PR to `main`, `feat/ai-edition` and `release/**`, and on every
- `npm run docs:check`
- `npx vite build` (renderer build smoke)
- `cargo test` / `cargo check` for the compositor on macOS, Windows and Linux
+- `swift test` and a release build of both macOS capture helpers
-All must be green before merge. Native helper code is NOT covered by CI — manual smoke test is required for `electron/*-helper/` changes; note it in the PR description.
+All must be green before merge. The macOS helpers have compile and unit-test coverage, but CI does not exercise real capture, permissions or devices. Manual smoke tests on the affected platforms are still required for native changes; note them in the PR description. See the [CI job inventory](../../technical-documentation/engineering/ci-workflows.md#tier-1-application-and-documentation-ci) for the exact checks and runners.
## Pull request flow
diff --git a/AGENTS.md b/AGENTS.md
index 268e56567..0f53b8cfc 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -70,7 +70,7 @@ every edit is the main way an agent turns a 5-minute task into a 30-minute one,
defined`. Don't add it to a test that doesn't need it: jsdom setup dominates this
suite's runtime (see the comment in `vitest.config.ts`).
- Anything platform-conditional (`process.platform`) must pin the platform in the test.
- CI is Linux-only, so a Linux-only code path left unpinned is green in CI and red on
+ The Vitest CI job runs only on Linux, so a Linux-only code path left unpinned is green in CI and red on
every Windows and macOS machine — `electron/recording/webm-seek-index.test.ts` is the
worked example.
- E2E tests are in `tests/e2e/` (Playwright). Some specs are platform-specific (e.g. `windows-native-checklist.spec.ts`).
@@ -171,7 +171,7 @@ The one rule to know before you merge anything: **there is one release branch pe
## Specialized notes
-- **Native capture is platform-fragile**: macOS uses ScreenCaptureKit (Swift), Windows uses WGC (C++/Win32). CI runs on Linux only — manual smoke test on real macOS/Windows is required for native changes.
+- **Native capture is platform-fragile**: macOS uses ScreenCaptureKit (Swift), Windows uses WGC (C++/Win32). CI tests and builds the macOS Swift helpers and checks the compositor on macOS, Windows and Linux. These checks do not exercise real capture, permissions or devices; manual smoke tests on the affected platforms are still required for native changes. See [CI coverage](technical-documentation/engineering/ci-workflows.md#tier-1-application-and-documentation-ci).
- **Rendering is native**: the Rust compositor in `crates/compositor/` renders the editor preview and every export, MP4 and GIF. It runs on Direct3D 11 on Windows, Metal on macOS and wgpu on Linux, with a CPU fallback on Windows and Linux. The renderer only paints the preview frames it pulls onto a `<canvas>`. Details: `technical-documentation/README.md`, then `architecture/native-compositor.md`.
- **i18n**: 15 locales in `src/i18n/locales/<locale>/` (e.g. `src/i18n/locales/en/settings.json`). The `i18n:check` script validates them — run it after touching translation files.
- **Website i18n** is separate: 8 locales under `website/i18n/`. After changing an English doc, page or `<Translate>` string in `website/`, follow `website/i18n/TRANSLATING.md` ("Keeping translations up to date"); `npm run i18n:check` in `website/` lists what is behind.
diff --git a/technical-documentation/engineering/ci-workflows.md b/technical-documentation/engineering/ci-workflows.md
index cc3ecea65..a87ca6734 100644
--- a/technical-documentation/engineering/ci-workflows.md
+++ b/technical-documentation/engineering/ci-workflows.md
@@ -7,9 +7,12 @@ The repository's 15 workflow files under `.github/workflows/` cover application
```mermaid
flowchart TD
subgraph T1["Tier 1 — application and docs CI"]
- CI["ci.yml<br/>push and PR to main"] --> Lint[lint]
- CI --> Type[typecheck]
- CI --> Test[unit and browser tests]
+ CI["ci.yml<br/>push and PR to configured branches"] --> Lint[lint]
+ CI --> Type[app and test typechecks]
+ CI --> Test[Vitest unit tests]
+ CI --> TechnicalDocs[technical documentation check]
+ CI --> Native["Rust compositor checks<br/>macOS, Windows, Linux"]
+ CI --> Swift[macOS Swift tests and release build]
CI --> BuildSmoke[Vite build]
CI --> Semantic[semantic PR title]
Docs["docs.yml<br/>website changes or dispatch"] --> DocsBuild[website build artifact]
@@ -58,7 +61,7 @@ The STT workflow uploads standalone archives for binary refresh and does not cur
| Tier | Workflow | Trigger |
|---|---|---|
-| 1 | `ci.yml` | Push to `main`; pull request to `main` |
+| 1 | `ci.yml` | Push and pull request to `main`, `feat/ai-edition`, `release/**` or `integration/**` |
| 1 | `docs.yml` | Website/workflow changes on `main` or a PR; manual dispatch |
| 2 | `build.yml` | Any `v*` tag; manual dispatch |
| 2 | `build-whisper-stt.yml` | Native STT/build-script changes; manual dispatch |
@@ -75,17 +78,26 @@ The STT workflow uploads standalone archives for binary refresh and does not cur
## Tier 1: application and documentation CI
-`ci.yml` runs independent `lint`, `typecheck`, `test`, and renderer-build jobs. Pull requests also run `semantic-pr`.
+[`ci.yml`](../../.github/workflows/ci.yml) runs the following independent jobs on pushes and pull requests to `main`, `feat/ai-edition`, `release/**` and `integration/**`. Only `semantic-pr` is restricted to pull requests.
| Job | Runner | Command or purpose |
|---|---|---|
| `lint` | Ubuntu | `npm run lint` |
| `typecheck` | Ubuntu | `npx tsc --noEmit` |
-| `test` | Ubuntu | Vitest unit tests, Chromium installation, then browser-mode Vitest |
+| `typecheck-tests` | Ubuntu | `npx tsc -p tsconfig.test.json --noEmit` |
+| `docs` | Ubuntu | `npm run docs:check` for `technical-documentation/` and `.harness/` |
+| `test` | Ubuntu | `npm run test` (Vitest unit tests; no browser-mode step) |
| `build` | Ubuntu | `npx vite build`; this is not electron-builder packaging |
| `appstream` | Ubuntu | `appstreamcli validate` on `build/com.getopenscreen.OpenScreen.metainfo.xml` |
+| `rust-macos-compositor-check` | `macos-latest` (arm64) | `cargo test -p openscreen-compositor --lib --tests`, then `cargo build -p compositor-view-napi --release` |
+| `rust-macos-intel-compositor-check` | `macos-15-intel` | Metal-device probe, then `cargo test -p openscreen-compositor --lib --tests` |
+| `rust-windows-compositor-check` | `windows-latest` | `cargo check -p openscreen-compositor -p compositor-view-napi --all-targets` |
+| `rust-linux-compositor-check` | `ubuntu-latest` | `cargo test -p openscreen-compositor --lib --tests`, then `cargo build -p compositor-view-napi --release` |
+| `swift-macos-helper` | `macos-latest` | `swift test` and `swift build -c release` for `electron/native/screencapturekit` |
| `semantic-pr` | Ubuntu | Validates Conventional Commit-style PR titles |
+The Vitest job is Linux-only; the native jobs do not change that, so platform-conditional TypeScript tests must still pin `process.platform`. The Windows compositor job checks compilation rather than running its tests. None of these jobs replaces the [manual desktop pass](../testing/manual-e2e-checklist.md) for real recording, OS permissions or physical devices.
+
`build/com.getopenscreen.OpenScreen.metainfo.xml` is upstream AppStream metadata: the name, summary, description, licence, screenshots and release history a software centre shows instead of a bare icon. Nothing in this repository consumes it yet — the shipped deb installs a `.desktop` file and nine icon sizes and no `/usr/share/metainfo/` at all — so the `appstream` job is the only thing that can catch a broken edit before a Flathub reviewer does. Its component ID is `com.getopenscreen.OpenScreen`, deliberately not the Electron `appId` `com.etiennelescot.openscreen`: Flathub requires the ID to map to a domain the project controls, and `getopenscreen.com` is that domain.
Jobs that need the root dependencies use `.github/actions/setup`, which requests Node 22 and runs `npm ci`; callers perform checkout themselves.
diff --git a/technical-documentation/testing/writing-tests.md b/technical-documentation/testing/writing-tests.md
index 83ae0a98b..a464690c4 100644
--- a/technical-documentation/testing/writing-tests.md
+++ b/technical-documentation/testing/writing-tests.md
@@ -43,7 +43,7 @@ it only if it renders a component, uses `renderHook`, or reaches for a browser g
### Platform-conditional code
-CI runs on Linux only. A test covering a `process.platform`-gated path must pin the
+The Vitest CI job runs only on Linux. A test covering a `process.platform`-gated path must pin the
platform itself, or it passes vacuously in CI and fails on every Windows and macOS
machine. `electron/recording/webm-seek-index.test.ts` sets `process.platform` in
`beforeEach` and restores it in `afterEach` — copy that shape.