Testing

• Unit / integration: new or changed logic in app/src/lib/, app/src/models/, git operations, store behavior, utility functions, IPC contracts.
• UI component: new or changed React components, dialog behavior, banners, toolbar items, list rendering.
• Ad-hoc E2E: only for temporary validation of a feature or bugfix across the full app. E2E tests you write are meant to be run locally and to capture screenshots/video for the PR, not to be merged into the permanent smoke suite.

Running Tests

# All unit and UI tests
yarn test

# A specific test file
yarn test app/test/unit/my-feature-test.ts

# All tests in a directory (recursive)
yarn test app/test/unit/ui

# E2E — build unpackaged app + run (fast local iteration)
yarn test:e2e:unpackaged

# E2E — run against an already-built unpackaged app
DESKTOP_E2E_APP_MODE=unpackaged npx playwright test --config app/test/e2e/playwright.config.ts

# E2E — full packaged build + run (production-like)
yarn test:e2e:packaged

The test runner (script/test.mjs) discovers files matching -test.(ts|tsx|js|jsx|mts|mjs) recursively in app/test/unit/ by default, or in the paths you pass.

Test Verification Workflow

After implementing any change you must run the full unit test suite:

yarn test

If any tests fail:

1. Determine whether the failure is a regression (a bug you introduced) or an expected behavior change (your change intentionally altered the behavior).
2. If it is a regression, fix the code.
3. If it is an expected change, update the test assertions so they reflect the new correct behavior.
4. Re-run the suite until everything passes.

Then verify linting:

yarn lint

If lint errors are reported and you want to auto-fix them:

yarn lint:fix

Note: yarn lint:fix rewrites files across the repository (Prettier + ESLint --fix). Only run it when you intend to apply those edits — do not use it as a read-only check.

Bug-First Testing

When fixing a bug:

1. Write a failing test first that reproduces the bug.
2. Verify the test fails.
3. Apply the fix.
4. Verify the test now passes.

This proves the fix works and protects against regressions.

Unit / Integration Tests (Non-UI)

File conventions

• Location: app/test/unit/, mirroring the source tree (e.g. app/src/lib/git/clone.ts → app/test/unit/git/clone-test.ts).
• File name: *-test.ts.
• Extension: .ts (use .tsx only when the file contains JSX).

Imports

import { describe, it, beforeEach } from 'node:test'
import assert from 'node:assert'

Use node:assert for all assertions — never Jest or Chai matchers.

Test structure

Synchronous tests are fine for pure logic:

describe('MyFeature', () => {
  it('does something useful', () => {
    const result = myFunction('input')
    assert.equal(result, 'expected')
  })
})

Use async when the test or its helpers need it. Pass the test context t when using helpers that register cleanup via t.after():

it('creates a repo', async t => {
  const repo = await setupEmptyRepository(t)
  // repo's temp directory is cleaned up automatically after the test
})

Assertion patterns

assert.equal vs assert.strictEqual: assert.equal(a, b) uses the == operator (abstract equality), so assert.equal(42, '42') passes. assert.strictEqual(a, b) uses ===, so it also checks that types match. Prefer assert.strictEqual in most cases to avoid silent type-coercion surprises. Use assert.equal only when you explicitly want coercion semantics.

Existing helpers — reuse them

Patterns to follow

Factory functions for dependencies — create stores, databases, and API instances through dedicated factory functions, not raw constructors:

const stores = createTestStores()
const api = createMockAPI({
  fetchRepository: async () => createMockAPIRepository(),
})

Promise wrappers with timeouts for callback-based async APIs:

async function waitForResult(store, ...args): Promise<Result> {
  return new Promise((resolve, reject) => {
    const timeout = setTimeout(
      () => reject(new Error('Timed out')),
      5_000
    )
    store.getResult(...args, result => {
      clearTimeout(timeout)
      resolve(result)
    })
  })
}

State machine testing — verify store transitions by calling methods and asserting intermediate states:

signInStore.beginDotComSignIn()
const state = signInStore.getState()
assert.equal(state?.kind, SignInStep.Authentication)

Compile-time contract verification — use TypeScript's type system to catch missing cases at compile time (see ipc-contract-test.ts for example):

type AssertExactUnion<TExpected, TActual> = [
  Exclude<TExpected, TActual>,
  Exclude<TActual, TExpected>,
] extends [never, never]
  ? true
  : never

UI Component Tests

File conventions

• Location: app/test/unit/ui/.
• File name: *-test.tsx (must be .tsx for JSX).

Critical import rule

Always import render utilities from the project's wrapper module:

import { render, fireEvent, screen, waitFor, within } from '../../helpers/ui/render'

Never import directly from @testing-library/react. The wrapper module (app/test/helpers/ui/render.tsx) imports app/test/helpers/ui/setup.ts as a side-effect, which:

1. Polyfills ResizeObserver (not available in JSDOM).
2. Aligns globalThis.Event/CustomEvent with the jsdom window versions.
3. Registers an afterEach(cleanup) hook so the DOM is cleaned between tests.

Skipping this import will cause test failures or leaks.

Rendering and querying

import assert from 'node:assert'
import { describe, it } from 'node:test'
import * as React from 'react'
import { render, screen, fireEvent } from '../../helpers/ui/render'

describe('MyComponent', () => {
  it('renders a button and responds to clicks', () => {
    let clicked = 0
    render(<MyComponent onClick={() => clicked++} />)

    const button = screen.getByRole('button', { name: 'Submit' })
    assert.ok(button)

    fireEvent.click(button)
    assert.equal(clicked, 1)
  })
})

Querying elements:

Assertions use node:assert, not Jest matchers:

assert.notEqual(view.container.querySelector('.my-class'), null)
assert.equal(screen.queryByRole('button', { name: 'Gone' }), null)

Re-rendering

const view = render(<MyComponent visible={true} />)
// ... assert initial state ...
view.rerender(<MyComponent visible={false} />)
// ... assert updated state ...

Callback verification

Capture callbacks in local variables and assert after interaction:

let dismissed = 0
render(<Banner onDismissed={() => dismissed++} />)
fireEvent.click(screen.getByRole('button', { name: 'Dismiss this message' }))
assert.equal(dismissed, 1)

Timer mocking

For components with timeouts (banners, auto-dismiss, debounce):

import { afterEach, beforeEach, describe, it } from 'node:test'
import {
  advanceTimersBy,
  enableTestTimers,
  resetTestTimers,
} from '../../helpers/ui/timers'

describe('auto-dismissing banner', () => {
  beforeEach(() => enableTestTimers(['setTimeout']))
  afterEach(() => resetTestTimers())

  it('dismisses after timeout', () => {
    let dismissed = 0
    render(<Banner timeout={500} onDismissed={() => dismissed++} />)

    advanceTimersBy(500)
    assert.equal(dismissed, 1)
  })
})

Clipboard testing

Register restore() in afterEach so the mock is always torn down even when an assertion throws:

import { afterEach, it } from 'node:test'
import { captureClipboardWrites } from '../../helpers/ui/electron'

describe('CopyButton', () => {
  let restore: () => void
  let writes: string[]

  afterEach(() => restore?.())

  it('copies text to clipboard', () => {
    ;({ writes, restore } = captureClipboardWrites())
    render(<CopyButton text="hello" />)
    fireEvent.click(screen.getByRole('button'))
    assert.deepEqual(writes, ['hello'])
  })
})

Calling restore() inline at the end of the test body is not safe — if any assertion before it throws, the global clipboard.writeText mock stays patched and will silently contaminate subsequent tests.

ESLint note

The react/jsx-no-bind rule is disabled for test files, so inline arrow functions in JSX are fine in tests.

Ad-hoc E2E Tests

E2E tests launch the real Desktop app via Playwright's Electron support. Use them only for temporary validation of your work — to capture screenshots and video for the Pull Request. Do not add tests to the permanent smoke suite (app-launch.e2e.ts) unless explicitly asked.

File conventions

• Location: app/test/e2e/.
• File name: *.e2e.ts (Playwright config matches this pattern).
• Do not modify app-launch.e2e.ts unless explicitly asked.

⚠️ Delete ad-hoc specs before opening your PR. Playwright's config matches every *.e2e.ts file in app/test/e2e/, so any file you create there will run in CI. Ad-hoc specs are for local validation only — stage and run them locally, then git rm them before committing.

Imports

import {
  test,
  expect,
  controlMockServer,
  getMockRequests,
  dismissMoveToApplicationsDialog,
} from './e2e-fixtures'
import type { Page } from '@playwright/test'

Test structure

test.describe.configure({ mode: 'serial' })

test.describe('My Feature E2E', () => {
  test('launches app and shows feature', async ({ mainWindow: page }) => {
    // Wait for the React app to mount
    await page.waitForFunction(
      () =>
        (document.getElementById('desktop-app-container')?.innerHTML.length ??
          0) > 100,
      null,
      { timeout: 30000 }
    )

    // ... interact with the app ...
  })
})

All tests run serially in the same Electron session (one app launch per test file).

Locating elements

// CSS selector
const button = page.locator('button:has-text("Finish")')

// XPath
const item = page.locator('//div[contains(@class, "list-item")]')

// Waiting for visibility
await button.waitFor({ state: 'visible', timeout: 15000 })

Setting React controlled inputs

For most inputs, Playwright's .fill() works fine. However, some React controlled inputs ignore .fill() because they rely on React's synthetic event system rather than native DOM events. If .fill() doesn't update the React state (i.e., the value appears empty after filling), use this workaround that fires both input and change events through React's internal value setter:

await input.evaluate((el, value) => {
  const inp = el as HTMLInputElement
  Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value')
    ?.set?.call(inp, value)
  inp.dispatchEvent(new Event('input', { bubbles: true }))
  inp.dispatchEvent(new Event('change', { bubbles: true }))
}, 'my-value')

Use .fill() first — only fall back to the workaround when .fill() does not produce the expected state change in React.

Assertions

Direct assertions on locators:

await expect(locator).toContainText('expected text', { timeout: 15000 })
await expect(locator).toBeVisible()
await expect(locator).not.toBeVisible()

Polling assertions for async conditions (git state, server requests):

await expect
  .poll(() => getSmokeRepoCurrentBranch(), {
    timeout: 15000,
    intervals: [1000],
  })
  .toBe('my-branch')

IPC events

Trigger menu events or app actions from the renderer:

await page.evaluate(() => {
  require('electron').ipcRenderer.emit('menu-event', {}, 'show-about')
})

Taking screenshots

Take screenshots at key UI moments during the test. Save them under playwright-videos/ so they are collected alongside videos:

await page.screenshot({
  path: 'playwright-videos/01-feature-dialog-open.png',
})

Name screenshots with a numeric prefix so they appear in order. Be