test(kernel-browser-runtime): Add CapTP infrastructure tests

      Add comprehensive tests for the CapTP infrastructure:
      - background-captp.test.ts: Tests for utility functions and makeBackgroundCapTP
      - kernel-facade.test.ts: Tests for facade delegation to kernel methods
      - kernel-captp.test.ts: Tests for makeKernelCapTP factory
      - captp.integration.test.ts: Full round-trip E() tests with real endoify

      Configure vitest with inline projects to use different setupFiles:
      - Unit tests use mock-endoify for isolated testing
      - Integration tests use real endoify for CapTP/E() functionality

      🤖 Generated with [Claude Code](https://claude.com/claude-code)

      Co-Authored-By: Claude Opus 4.5 <[email protected]>

Author: rekmarks

packages/kernel-browser-runtime/package.json

@@ -83,6 +83,7 @@
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.17.4",
+    "@endo/eventual-send": "^1.3.4",
     "@metamask/auto-changelog": "^5.0.1",
     "@metamask/eslint-config": "^14.0.0",
     "@metamask/eslint-config-nodejs": "^14.0.0",

packages/kernel-browser-runtime/src/background-captp.test.ts

@@ -0,0 +1,166 @@
+import '@ocap/repo-tools/test-utils/mock-endoify';
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+import {
+  isCapTPNotification,
+  getCapTPMessage,
+  makeCapTPNotification,
+  makeBackgroundCapTP,
+} from './background-captp.ts';
+import type { CapTPMessage, CapTPNotification } from './background-captp.ts';
+
+describe('isCapTPNotification', () => {
+  it('returns true for valid CapTP notification', () => {
+    const notification = {
+      jsonrpc: '2.0',
+      method: 'captp',
+      params: [{ type: 'foo' }],
+    };
+    expect(isCapTPNotification(notification)).toBe(true);
+  });
+
+  it('returns false when method is not "captp"', () => {
+    const message = {
+      jsonrpc: '2.0',
+      method: 'other',
+      params: [{ type: 'foo' }],
+    };
+    expect(isCapTPNotification(message)).toBe(false);
+  });
+
+  it('returns false when params is not an array', () => {
+    const message = {
+      jsonrpc: '2.0',
+      method: 'captp',
+      params: { type: 'foo' },
+    };
+    expect(isCapTPNotification(message as never)).toBe(false);
+  });
+
+  it('returns false when params is empty', () => {
+    const message = {
+      jsonrpc: '2.0',
+      method: 'captp',
+      params: [],
+    };
+    expect(isCapTPNotification(message)).toBe(false);
+  });
+
+  it('returns false when params has more than one element', () => {
+    const message = {
+      jsonrpc: '2.0',
+      method: 'captp',
+      params: [{ type: 'foo' }, { type: 'bar' }],
+    };
+    expect(isCapTPNotification(message)).toBe(false);
+  });
+
+  it('returns true for JSON-RPC request with id if it matches captp format', () => {
+    // A request with an id is still a valid captp message format-wise
+    const request = {
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'captp',
+      params: [{ type: 'foo' }],
+    };
+    expect(isCapTPNotification(request)).toBe(true);
+  });
+});
+
+describe('getCapTPMessage', () => {
+  it('extracts CapTP message from valid notification', () => {
+    const captpMessage: CapTPMessage = { type: 'CTP_CALL', methargs: [] };
+    const notification: CapTPNotification = {
+      jsonrpc: '2.0',
+      method: 'captp',
+      params: [captpMessage],
+    };
+    expect(getCapTPMessage(notification)).toStrictEqual(captpMessage);
+  });
+
+  it('throws for non-CapTP notification', () => {
+    const message = {
+      jsonrpc: '2.0',
+      method: 'other',
+      params: [],
+    };
+    expect(() => getCapTPMessage(message)).toThrow('Not a CapTP notification');
+  });
+
+  it('throws when params is empty', () => {
+    const message = {
+      jsonrpc: '2.0',
+      method: 'captp',
+      params: [],
+    };
+    expect(() => getCapTPMessage(message)).toThrow('Not a CapTP notification');
+  });
+});
+
+describe('makeCapTPNotification', () => {
+  it('wraps CapTP message in JSON-RPC notification', () => {
+    const captpMessage: CapTPMessage = { type: 'CTP_CALL', target: 'ko1' };
+    const result = makeCapTPNotification(captpMessage);
+
+    expect(result).toStrictEqual({
+      jsonrpc: '2.0',
+      method: 'captp',
+      params: [captpMessage],
+    });
+  });
+
+  it('creates valid notification that passes isCapTPNotification', () => {
+    const captpMessage: CapTPMessage = { type: 'CTP_RESOLVE' };
+    const notification = makeCapTPNotification(captpMessage);
+
+    expect(isCapTPNotification(notification)).toBe(true);
+  });
+});
+
+describe('makeBackgroundCapTP', () => {
+  let sendMock: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    sendMock = vi.fn();
+  });
+
+  it('returns object with dispatch, getKernel, and abort', () => {
+    const capTP = makeBackgroundCapTP({ send: sendMock });
+
+    expect(capTP).toHaveProperty('dispatch');
+    expect(capTP).toHaveProperty('getKernel');
+    expect(capTP).toHaveProperty('abort');
+    expect(typeof capTP.dispatch).toBe('function');
+    expect(typeof capTP.getKernel).toBe('function');
+    expect(typeof capTP.abort).toBe('function');
+  });
+
+  it('getKernel returns a promise', () => {
+    const capTP = makeBackgroundCapTP({ send: sendMock });
+    const result = capTP.getKernel();
+
+    expect(result).toBeInstanceOf(Promise);
+  });
+
+  it('calls send function when dispatching bootstrap request', () => {
+    const capTP = makeBackgroundCapTP({ send: sendMock });
+
+    // Calling getKernel triggers a bootstrap request (ignore unhandled promise)
+    capTP.getKernel().catch(() => undefined);
+
+    // CapTP should have sent a message to request bootstrap
+    expect(sendMock).toHaveBeenCalled();
+    const sentMessage = sendMock.mock.calls[0][0] as CapTPMessage;
+    expect(sentMessage).toBeDefined();
+  });
+
+  it('dispatch returns boolean', () => {
+    const capTP = makeBackgroundCapTP({ send: sendMock });
+
+    // Dispatch a dummy message (will return false since it's not a valid CapTP message)
+    const result = capTP.dispatch({ type: 'unknown' });
+
+    expect(typeof result).toBe('boolean');
+  });
+});

packages/kernel-browser-runtime/src/index.test.ts

@@ -1,3 +1,5 @@
+import '@ocap/repo-tools/test-utils/mock-endoify';
+
 import { describe, expect, it } from 'vitest';
 
 import * as indexModule from './index.ts';

packages/kernel-browser-runtime/src/kernel-worker/captp/captp.integration.test.ts

@@ -0,0 +1,194 @@
+// Real endoify needed for CapTP and E() to work properly
+// eslint-disable-next-line import-x/no-extraneous-dependencies
+import '@metamask/kernel-shims/endoify';
+
+import { E } from '@endo/eventual-send';
+import type { ClusterConfig, Kernel } from '@metamask/ocap-kernel';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+import { makeKernelCapTP } from './kernel-captp.ts';
+import { makeBackgroundCapTP } from '../../background-captp.ts';
+import type { CapTPMessage } from '../../background-captp.ts';
+
+/**
+ * Integration tests for CapTP communication between background and kernel endpoints.
+ *
+ * These tests validate that the two CapTP endpoints can communicate correctly
+ * and that E() works properly with the kernel facade remote presence.
+ */
+describe('CapTP Integration', () => {
+  let mockKernel: Kernel;
+  let kernelCapTP: ReturnType<typeof makeKernelCapTP>;
+  let backgroundCapTP: ReturnType<typeof makeBackgroundCapTP>;
+
+  beforeEach(() => {
+    // Create mock kernel with method implementations
+    mockKernel = {
+      launchSubcluster: vi.fn().mockResolvedValue({
+        body: '#{"rootKref":"ko1"}',
+        slots: ['ko1'],
+      }),
+      terminateSubcluster: vi.fn().mockResolvedValue(undefined),
+      queueMessage: vi.fn().mockResolvedValue({
+        body: '#{"result":"message-sent"}',
+        slots: [],
+      }),
+      getStatus: vi.fn().mockResolvedValue({
+        vats: [{ id: 'v1', name: 'test-vat' }],
+        subclusters: ['sc1'],
+        remoteComms: false,
+      }),
+      pingVat: vi.fn().mockResolvedValue({
+        pingVatResult: 'pong',
+        roundTripMs: 5,
+      }),
+    } as unknown as Kernel;
+
+    // Wire up CapTP endpoints to dispatch messages synchronously to each other
+    // This simulates direct message passing for testing
+
+    // Kernel-side: exposes facade as bootstrap
+    kernelCapTP = makeKernelCapTP({
+      kernel: mockKernel,
+      send: (message: CapTPMessage) => {
+        // Dispatch synchronously for testing
+        backgroundCapTP.dispatch(message);
+      },
+    });
+
+    // Background-side: gets remote presence of kernel
+    backgroundCapTP = makeBackgroundCapTP({
+      send: (message: CapTPMessage) => {
+        // Dispatch synchronously for testing
+        kernelCapTP.dispatch(message);
+      },
+    });
+  });
+
+  describe('bootstrap', () => {
+    it('background can get kernel remote presence via getKernel', async () => {
+      // Request the kernel facade - with synchronous dispatch, this resolves immediately
+      const kernel = await backgroundCapTP.getKernel();
+      expect(kernel).toBeDefined();
+    });
+  });
+
+  describe('ping', () => {
+    it('e(kernel).ping() returns "pong"', async () => {
+      // Get kernel remote presence
+      const kernel = await backgroundCapTP.getKernel();
+
+      // Call ping via E()
+      const result = await E(kernel).ping();
+      expect(result).toBe('pong');
+    });
+  });
+
+  describe('getStatus', () => {
+    it('e(kernel).getStatus() returns status from mock kernel', async () => {
+      // Get kernel remote presence
+      const kernel = await backgroundCapTP.getKernel();
+
+      // Call getStatus via E()
+      const result = await E(kernel).getStatus();
+      expect(result).toStrictEqual({
+        vats: [{ id: 'v1', name: 'test-vat' }],
+        subclusters: ['sc1'],
+        remoteComms: false,
+      });
+
+      expect(mockKernel.getStatus).toHaveBeenCalled();
+    });
+  });
+
+  describe('launchSubcluster', () => {
+    it('e(kernel).launchSubcluster() passes arguments correctly', async () => {
+      const config: ClusterConfig = {
+        bootstrap: 'v1',
+        vats: {
+          v1: {
+            bundleSpec: 'test-source',
+          },
+        },
+      };
+
+      // Get kernel remote presence
+      const kernel = await backgroundCapTP.getKernel();
+
+      // Call launchSubcluster via E()
+      const result = await E(kernel).launchSubcluster(config);
+      expect(result).toStrictEqual({
+        body: '#{"rootKref":"ko1"}',
+        slots: ['ko1'],
+      });
+
+      expect(mockKernel.launchSubcluster).toHaveBeenCalledWith(config);
+    });
+  });
+
+  describe('terminateSubcluster', () => {
+    it('e(kernel).terminateSubcluster() delegates to kernel', async () => {
+      // Get kernel remote presence
+      const kernel = await backgroundCapTP.getKernel();
+
+      // Call terminateSubcluster via E()
+      await E(kernel).terminateSubcluster('sc1');
+      expect(mockKernel.terminateSubcluster).toHaveBeenCalledWith('sc1');
+    });
+  });
+
+  describe('queueMessage', () => {
+    it('e(kernel).queueMessage() passes arguments correctly', async () => {
+      const target = 'ko1';
+      const method = 'doSomething';
+      const args = ['arg1', { nested: 'value' }];
+
+      // Get kernel remote presence
+      const kernel = await backgroundCapTP.getKernel();
+
+      // Call queueMessage via E()
+      const result = await E(kernel).queueMessage(target, method, args);
+      expect(result).toStrictEqual({
+        body: '#{"result":"message-sent"}',
+        slots: [],
+      });
+
+      expect(mockKernel.queueMessage).toHaveBeenCalledWith(
+        target,
+        method,
+        args,
+      );
+    });
+  });
+
+  describe('pingVat', () => {
+    it('e(kernel).pingVat() delegates to kernel', async () => {
+      // Get kernel remote presence
+      const kernel = await backgroundCapTP.getKernel();
+
+      // Call pingVat via E()
+      const result = await E(kernel).pingVat('v1');
+      expect(result).toStrictEqual({
+        pingVatResult: 'pong',
+        roundTripMs: 5,
+      });
+
+      expect(mockKernel.pingVat).toHaveBeenCalledWith('v1');
+    });
+  });
+
+  describe('error propagation', () => {
+    it('errors from kernel methods propagate to background', async () => {
+      const error = new Error('Kernel operation failed');
+      vi.mocked(mockKernel.getStatus).mockRejectedValueOnce(error);
+
+      // Get kernel remote presence
+      const kernel = await backgroundCapTP.getKernel();
+
+      // Call getStatus which will fail
+      await expect(E(kernel).getStatus()).rejects.toThrow(
+        'Kernel operation failed',
+      );
+    });
+  });
+});