Skip to content

IPC Contract Testing — validate renderer↔main channel contracts #7

Closed

Description

@fhemmerrelias

Overview

The 16 IPC handler files in electron/ipc/ register channels that the renderer process calls via window.terminal, window.github, etc. There is currently zero validation that these channel contracts are maintained — a renamed or removed channel silently breaks features at runtime. We need contract tests that verify each handler registers the expected channels and that request/response shapes match what the renderer sends and expects.

Architecture

  • Shared IPC_CHANNELS constant — single source of truth for all channel names, generated from or consumed by both main and renderer
  • Contract test suite — auto-discovers handler files, verifies each registers expected channels, validates request/response types
  • Highest-risk files: githubHandlers.ts (27KB, most complex), terminalHandlers.ts (14KB), configHandlers.ts (7KB)

Implementation Steps

1. Create shared IPC channel constants

Create electron/ipc/ipcChannels.ts (or generate from TypeScript types) that defines every channel name as a typed constant. Both main process handlers and renderer preload/API code must import from this single source.

// electron/ipc/ipcChannels.ts
export const IPC_CHANNELS = {
  github: {
    listPRs: 'github:list-prs',
    getPRDetail: 'github:get-pr-detail',
    // ... all channels from githubHandlers.ts
  },
  terminal: {
    create: 'terminal:create',
    readDir: 'terminal:read-dir',
    // ... all channels from terminalHandlers.ts
  },
  // ... all 16 handler namespaces
} as const;

2. Write contract tests for each handler

In each electron/ipc/*Handlers.test.ts, add contract verification tests:

// Verify the handler registers all expected channels
it('registers all expected github channels', () => {
  const registeredChannels = getRegisteredChannels();
  const expectedChannels = Object.values(IPC_CHANNELS.github);
  expect(registeredChannels).toContainAll(expectedChannels);
});

3. Test request/response shape contracts

For each channel, validate that the renderer call signatures match the handler's expected input types:

it('github:list-prs accepts correct request shape', () => {
  const handler = getHandler(IPC_CHANNELS.github.listPRs);
  // Verify handler accepts the shape the renderer sends
  expect(() => handler(validListPRsRequest)).not.toThrow();
});

4. Add CI gate

Add test:ipc-contracts script to package.json and wire into CI so that contract regressions block the build.

Acceptance Criteria

  • electron/ipc/ipcChannels.ts exists with all channel names as typed constants
  • All 16 handler files import channel names from the shared constant (no hardcoded strings)
  • Contract tests verify each handler registers expected channels
  • Contract tests verify request/response shapes match renderer expectations
  • test:ipc-contracts script added and runs in CI
  • No hardcoded channel strings remain in renderer or main process code

Activity

  1. added 2 commits that reference this issue on May 6, 2026
    01c9ac2
    7fa0e3e
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions