Skip to content

Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.

5.5 KB
Raw Blame
// server/tests/support/stub-broker.ts
/**
 * A `ConnectedAppBroker` test double whose every member the test did not provide FAILS LOUDLY.
 *
 * WHY THIS EXISTS. Broker stubs drifted from the seam in two ways, and the type checker saw
 * neither:
 *
 *   - CAST PAST THE TYPE. `{ … } as unknown as ConnectedAppBroker` or `{} as ConnectedAppBroker`
 *     makes a stub that omits `revoke` and `revokeAccount` compile. The compiler's guarantee is
 *     gone exactly as it was when a broken `import type` degraded the type to `any` (round-2 C8).
 *     Use this factory instead so missing methods remain type errors.
 *   - A PLAUSIBLE DEFAULT. `revokeAccount: async () => {}` type-checks and answers "done" for a
 *     revoke that never happened. A test can then pass on a fiction, and the revoke seam is the
 *     one this PR's Claim 2 is about.
 *
 * So the factory takes the members a test actually means, and everything else becomes a member
 * that RECORDS that it was reached and THROWS. This hoists round-2 C8a's `unasked` pattern into one
 * place: a throw alone is only as loud as the path that receives it — a `catch` in production
 * swallows it and the test passes — which is why each reach is also recorded, and
 * {@link BrokerStub.expectNothingUnprovidedReached} (run it in an `afterEach`) reads the record.
 *
 * WHAT THE SIGNATURE FORCES.
 *
 *   - `grantIsLocal` and `authorizations` are REQUIRED. They are declarations, not behaviour; the
 *     seam makes a broker SAY them (see `ConnectedAppBroker.authorizations`), and a factory that
 *     defaulted them would reintroduce the plausible-default defect one field along.
 *   - Every method is optional, and an omitted one throws. There is no default that returns a
 *     value, on purpose: a test that needs `revokeAccount` to succeed writes that, in its own file,
 *     where a reviewer reads it.
 *   - The result is built as a `ConnectedAppBroker` OBJECT LITERAL with no cast, so adding a member
 *     to the seam fails `typecheck:tests` here until the factory learns it, instead of every stub
 *     in the suite silently lacking it.
 *
 * Every call to a PROVIDED member is recorded too, in {@link BrokerStub.calls}, so an honest stub
 * that wants to assert "revokeAccount was asked for ca_1" does not have to hand-roll a recorder.
 */
import { expect } from "bun:test";
import type { ConnectedAppBroker } from "../../src/plugins/broker";

/** The members a broker DECLARES rather than does. Required: there is no honest default. */
type Declared = "grantIsLocal" | "authorizations";

/** What a test hands {@link stubBroker}: the declarations, plus whichever methods it means. */
export type StubBrokerInput = Pick<ConnectedAppBroker, Declared> &
  Partial<Omit<ConnectedAppBroker, Declared>>;

/** The name of a broker method, i.e. every member that is not a declaration. */
export type BrokerMethod = Exclude<keyof ConnectedAppBroker, Declared>;

export type BrokerStub = {
  /** The double itself, typed as the seam with no cast. */
  broker: ConnectedAppBroker;
  /** Every call to a member the test PROVIDED, in order. */
  calls: Array<{ member: BrokerMethod; args: unknown[] }>;
  /** Every call to a member the test did NOT provide, in order — each of which also threw. */
  unprovided: BrokerMethod[];
  /** Asserts no unprovided member was reached since the last check, and clears the record. */
  expectNothingUnprovidedReached(): void;
};

/** The sentence an unprovided member throws, exported so a test can match it exactly. */
export function unprovidedMessage(member: BrokerMethod): string {
  return `stubBroker: production reached broker.${member}, which this test did not provide`;
}

export function stubBroker(input: StubBrokerInput): BrokerStub {
  const calls: BrokerStub["calls"] = [];
  const unprovided: BrokerMethod[] = [];

  /**
   * The provided member, recorded; or, when absent, a member that records and throws.
   *
   * The throw is SYNCHRONOUS. Every broker method returns a promise, so an `await` sees it the
   * same as a rejection, while a fire-and-forget `.catch(() => {})` cannot swallow it.
   */
  function member<F extends (...args: never[]) => unknown>(
    name: BrokerMethod,
    provided: F | undefined,
  ): ((...args: Parameters<F>) => ReturnType<F>) | (() => never) {
    if (provided === undefined) {
      return () => {
        unprovided.push(name);
        throw new Error(unprovidedMessage(name));
      };
    }
    return (...args: Parameters<F>) => {
      calls.push({ member: name, args });
      return provided(...args) as ReturnType<F>;
    };
  }

  const broker: ConnectedAppBroker = {
    grantIsLocal: input.grantIsLocal,
    authorizations: input.authorizations,
    grantsFor: member("grantsFor", input.grantsFor),
    authProviderOf: member("authProviderOf", input.authProviderOf),
    listApps: member("listApps", input.listApps),
    ensureAuthConfig: member("ensureAuthConfig", input.ensureAuthConfig),
    deleteAuthConfig: member("deleteAuthConfig", input.deleteAuthConfig),
    authorize: member("authorize", input.authorize),
    isConnected: member("isConnected", input.isConnected),
    revoke: member("revoke", input.revoke),
    connectionFields: member("connectionFields", input.connectionFields),
    connectWithFields: member("connectWithFields", input.connectWithFields),
    revokeAccount: member("revokeAccount", input.revokeAccount),
    accountName: member("accountName", input.accountName),
  };

  return {
    broker,
    calls,
    unprovided,
    expectNothingUnprovidedReached() {
      expect(unprovided.splice(0)).toEqual([]);
    },
  };
}