nexus
测试

使用 createMockNexus 进行单元测试

使用可注入的 mock 对消费 Nexus 的应用代码进行单元测试。

当被测试代码接受或读取 NexusInstance,且你希望在没有真实 Nexus 拓扑的情况下进行确定性单元测试时,使用 createMockNexus()。

安装

pnpm add -D @nexus-js/testing

消费服务的模块

应用代码可以直接接受 NexusInstance:

import type { NexusInstance } from "@nexus-js/core";
import { UserToken } from "./shared";

export async function loadUserName(nexus: NexusInstance, id: string) {
  const connection = await nexus.connect({
    target: { context: "background" },
  });
  const users = connection.get(UserToken);

  return (await users.getUser(id)).name;
}

单元测试在同一个 Token 后注册服务:

import { createMockNexus } from "@nexus-js/testing";
import { UserToken, type UserService } from "./shared";
import { loadUserName } from "./load-user-name";

const mock = createMockNexus();

const users: UserService = {
  async getUser(id) {
    return { id, name: "Ada" };
  },
};

mock.service(UserToken, users);

await expect(loadUserName(mock.nexus, "u1")).resolves.toBe("Ada");

expect(mock.calls.connect()).toHaveLength(1);

React 组件测试

直接使用 NexusProvider。测试 package 不添加 React 子路径或单独的 provider abstraction。

import { render } from "@testing-library/react";
import { NexusProvider } from "@nexus-js/react";
import { createMockNexus } from "@nexus-js/testing";

const mock = createMockNexus();
mock.service(UserToken, users);

const wrapper = ({ children }: { children: React.ReactNode }) => (
  <NexusProvider nexus={mock.nexus}>{children}</NexusProvider>
);

render(<UserPanel />, { wrapper });

测试连接边界

mock 的 connection seam 让应用测试可以检验 connection acquisition 和 service lookup 的形状。 连接失败、handshake、授权、断开和重连请使用 Core 或适配器集成测试;mock 不模拟这些 runtime 行为。

const connection = await mock.nexus.connect({
  target: { context: "background" },
});
const result = connection.safeGet(UserToken);

if (result.isErr()) throw result.error;
await result.value.getUser("u1");

在测试中配置服务

mock.nexus.configure({ providers }) 记录配置并注册 provider:

mock.nexus.configure({
  providers: [{ token: UserToken, service: users }],
});

expect(mock.calls.configure()).toHaveLength(1);

mock.service(Token, implementation) 是无 scope 的注册。当测试需要在连接获取期间进行 where filtering 时,将 provider metadata 作为第三个可选参数传入。

mock 保存 config.policy 供断言,但不会执行 canConnect 或 canCall。

Release 和清理断言

release 和 safeRelease 适用于远程引用,不适用于普通服务 proxy。 用被测服务返回的远程引用测试这些调用;丢弃根 service proxy 不会关闭共享 connection。

选择和 Multicast

connect({ target, where, timeout, signal }) 获取一个 ready mock session;没有 target 时模拟被动获取,永远不会发现 provider。 connectMulticast(...) 返回固定 collection,其 get(Token) 方法返回每个 connection 的 Result。 mock 不模拟真实 connection acquisition 或 provider-catalog negotiation。

新的 connection lifecycle 请使用 Core 或适配器集成测试。mock 不建立真实连接、不执行 onConnect 或 subscribeIdentity,也不验证 collection snapshot。

真实获取、provider-catalog protocol、where(contextMeta, connectionMeta) 和适配器拓扑请使用 core 或适配器集成测试。

在测试之间清除状态

afterEach(() => {
  mock.clear();
});

clear(token) 移除该 token 注册的 service 和 connection record。 clear() 移除所有已注册 service、注入的 failure、connection record、configure record、release record 和 update-identity record。

边界

createMockNexus() 在 Nexus API seam 测试应用行为。它不验证:

  • endpoint implementation 正确性
  • browser postMessage
  • Chrome runtime port
  • Node socket path、framing 或 auth
  • 适配器 metadata 收集
  • 真实断开或重连顺序
  • daemon restart 或 iframe reload 行为
  • Core authorization policy 执行
  • transport graph、动态 discovery 或适配器 connection-metadata evaluation
在 GitHub 上编辑此页