Inngest 端到端测试实战指南本地 Dev Server 构建、测试过滤与 Connect Gateway 调试【免费下载链接】inngestThe leading workflow orchestration platform. Run stateful step functions and AI workflows on serverless, servers, or the edge.项目地址: https://gitcode.com/GitHub_Trending/in/inngest本指南基于 Inngest 仓库根目录下的 TESTING.md系统讲解如何用本地代码构建 Dev Server、启动 JS SDK 并运行 Go 端到端测试套件同时覆盖测试过滤、环境变量语义与 Connect Gateway 详细日志的开启方法。读完本文你将掌握 Inngest 完整的本地 E2E 测试工作流并能从源码层面理解测试基础设施的运作原理。一、测试体系总览Inngest 的测试体系分为两层单元测试直接运行在 Go 包内部的go test ./pkg/...等验证各模块的独立行为端到端测试E2E位于仓库根目录的tests/目录下需要完整的运行环境——一个本地 Dev Server 实例、一个真实运行的 SDK 应用以及测试进程三者协同工作。TESTING.md 中描述的三步流程正是 E2E 测试的标准启动路径也是本指南的核心内容。三步流程概览用本地代码构建并启动 Dev Server启动 JS SDKNext.js 应用作为被测函数宿主通过环境变量将测试进程指向上述两个服务运行go test测试套件。二、第一步用本地构建启动 Dev Server基本命令go run ./cmd dev --no-discovery这是 TESTING.md 给出的第一步命令。与直接使用npx inngest-clilatest dev安装预编译 CLI不同go run ./cmd dev会编译当前仓库的源码并运行确保你测试的是本地改动后的行为——这正是贡献者验证自己代码修改的首选方式。--no-discovery的作用--no-discovery用于禁用应用自动发现。默认情况下Dev Server 会自动扫描并连接本地运行的应用例如开发中的 Next.js 应用但在测试场景中应用地址由SDK_URL环境变量显式指定自动发现反而可能引入不确定性。从 cmd/devserver/cmd.go 的源码可以看到cli.BoolFlag{ Name: no-discovery, Usage: Disable app auto-discovery, },而 cmd/devserver/devserver.go 将其映射为Autodiscover: !noDiscovery最终传入devserver.StartOpts。也就是说--no-discovery等价于将自动发现开关置为关闭。Dev Server 常用启动参数结合 cmd/devserver/cmd.go 中的 CLI 定义测试场景中常用的参数如下参数默认值说明--port/-p8288见 pkg/api/api.goDev Server 的 API 端口测试中的API_URL需与此一致--host空Inngest 服务监听地址--no-discoveryfalse关闭应用自动发现--no-pollfalse关闭对应用的轮询更新--poll-interval5秒pkg/devserver/devserver.go应用更新的轮询间隔--queue-workers100pkg/devserver/devserver.go从队列执行步骤的执行器 worker 数--tick150毫秒pkg/devserver/devserver.go执行器轮询队列的间隔--persistfalse重启之间持久化数据--log-level/-linfo日志级别trace、debug、info、warn、errorcmd/root.go例如指定日志级别与端口运行go run ./cmd dev --no-discovery --log-level debug -p 8288启动健康检查仓库根目录的 tests.sh 脚本展示了官方如何等待 Dev Server 就绪——通过轮询健康检查端点while [ $attempt -lt $max_attempts ]; do if curl -s -f http://127.0.0.1:8288/health /dev/null 21; then echo Dev server started successfully break fi ... done这意味着你可以用curl http://127.0.0.1:8288/health快速验证 Dev Server 是否已启动成功再继续后续步骤。三、第二步启动 JS SDK基本命令cd tests/js yarn dev注意TESTING.md 使用yarn dev仓库根目录的 tests.sh 使用pnpm install --frozen-lockfile与pnpm dev。请根据你本地的包管理器与 tests/js/package.json 的实际脚本选择其一。tests/js是一个 Next.js 应用参见 tests/js/next.config.js其作用是为 E2E 测试提供真实的 SDK 函数宿主。测试套件通过SDK_URL环境变量指向它Dev Server 则通过该地址调用 SDK 暴露的函数。默认情况下SDK 开发服务器监听http://127.0.0.1:3000/api/inngest这与下文测试命令中的SDK_URLhttp://127.0.0.1:3000/api/inngest一一对应。四、第三步运行 E2E 测试标准测试命令INNGEST_SIGNING_KEYtest API_URLhttp://127.0.0.1:8288 SDK_URLhttp://127.0.0.1:3000/api/inngest go test ./tests -v -count1环境变量语义测试入口 tests/main.go 定义了以下环境变量环境变量含义示例值SDK_URLSDK 应用的地址/api/inngest端点http://127.0.0.1:3000/api/inngestAPI_URLDev Server / Inngest API 地址http://127.0.0.1:8288EVENT_URL事件发送地址未设置时默认取API_URLhttp://127.0.0.1:8288INNGEST_SIGNING_KEY函数注册与鉴权使用的签名密钥test开发环境值INNGEST_EVENT_KEY发送事件所用的 Event Key未设置时默认eventkeyeventkeyPROXY_URL测试代理服务器前缀默认http://localhosthttp://localhost其中EVENT_URL的逻辑在 tests/main.go 中体现当未显式设置时自动回退到API_URL因为 Dev Server 同时承载事件 API 与核心 API。命令参数解析go test ./tests运行仓库根目录下tests/包中的全部 E2E 测试-v输出每个测试的详细执行过程-count1禁用 Go 测试缓存确保每次都真实执行。这对 E2E 测试至关重要——它们依赖外部服务状态缓存结果毫无意义。测试运行机制tests/main.go中的run()函数tests/main.go揭示了 E2E 测试的内部机制在随机端口40000~50000启动一个测试代理服务器拦截执行器与 SDK 之间的所有 HTTP 请求通过introspect()调用 SDK 的/api/introspect端点确认被测函数存在将函数注册到 Dev Server/fn/register并把步骤的 URL 重写为代理地址测试过程中断言代理捕获的请求/响应是否符合预期测试结束后通过/fn/remove注销应用。这种方式让测试既能真实驱动执行器-SDK 交互又能精确断言消息内容。五、过滤测试只跑你关心的用例使用-test.run过滤INNGEST_SIGNING_KEYtest API_URLhttp://127.0.0.1:8288 SDK_URLhttp://127.0.0.1:3000/api/inngest go test ./tests -v -count1 -test.run TestSDKCancelNotReceived-test.run接受正则表达式匹配测试函数的名称。上面这条命令只运行TestSDKCancelNotReceived该测试位于 tests/sdk_cancel_test.go验证取消事件未收到时 step 串行执行step.run→step.sleep→step.run的行为Timeout 为 20 秒。过滤技巧精确匹配单个用例-test.run ^TestSDKCancelNotReceived$匹配一组用例-test.run TestStep会运行所有名称包含TestStep的测试配合子测试-test.run TestSDKCancelNotReceived/Without_a_cancellation_event可进一步过滤到某个t.Run子测试见 tests/sdk_cancel_test.go。官方脚本的过滤封装仓库根目录的 tests.sh 支持透传测试模式./tests.sh TestSDKCancelNotReceived脚本会先安装依赖、启动 JS SDK、等待 Dev Server 健康检查通过再以-run $TEST_PATTERN运行./tests包之后还会运行./tests/golang下的 Go SDK 测试例如 tests/golang/connect_test.go 中的TestEndToEnd覆盖 Connect Gateway 的长连接工作流。六、Connect Gateway 详细日志背景为什么默认看不到 Connect 日志Inngest 的 Connect Gateway 是处理 SDK 长连接WebSocket的组件。在 Dev Server 模式下为了避免日志噪音默认会抑制 Connect Gateway 的详细日志。这一行为在 pkg/connect/service.go 中实现func (c *connectGatewaySvc) Pre(ctx context.Context) error { // Set up gateway-specific logger with info for correlations c.logger logger.StdlibLogger(ctx).With(gateway_id, c.gatewayId) if c.dev { // Hide verbose connect gateway logs in dev server by default if os.Getenv(CONNECT_GATEWAY_FULL_LOGS) ! true { c.logger logger.VoidLogger() } } ... }可以看到当处于 dev 模式c.dev为 true且环境变量CONNECT_GATEWAY_FULL_LOGS不等于true时日志器被替换为logger.VoidLogger()即所有日志被丢弃。开启详细日志CONNECT_GATEWAY_FULL_LOGStrue go run ./cmd dev --no-discovery --log-level trace与普通启动相比这里有两个关键点CONNECT_GATEWAY_FULL_LOGStrue环境变量让 Connect Gateway 恢复日志输出--log-level trace将全局日志级别提升到trace输出最详尽的信息。TESTING.md 明确指出这是在需要调试 Connect Gateway 时的做法例如排查 SDK 连接建立、心跳、租约续期lease、pause 消息等长连接问题。日志中的关联字段开启后Connect Gateway 的日志会带上关联信息方便在多实例场景下追踪。从 pkg/connect/service.go 可以看到c.logger c.logger.With( gateway_group, c.groupName, gateway_hostname, c.hostname, gateway_ip, c.ipAddress.String(), )即每条日志会包含gateway_id、gateway_group、gateway_hostname、gateway_ip等字段可用于跨日志行串联分析某个网关实例的行为。七、一条命令跑完tests.sh 脚本如果想跳过手工三步流程可以直接使用仓库根目录的 tests.sh 自动化脚本。它的执行流程是清理占用端口8288的残留进程安装tests/js依赖并后台启动 JS SDKpnpm dev后台启动go run ./cmd dev --no-discovery将输出重定向到dev-stdout.txt/dev-stderr.txt轮询http://127.0.0.1:8288/health等待 Dev Server 就绪最多 10 次、每次间隔 1 秒运行./tests的 Go E2E 测试支持传入-run模式过滤运行./tests/golang的 Go SDK 测试捕获SIGINT/SIGTERM后清理全部后台进程。使用方式# 全部测试 ./tests.sh # 仅运行指定测试 ./tests.sh TestSDKCancelNotReceived八、常见问题排查1. 端口被占用或测试串扰多个测试会话同时运行会争用8288、3000端口。参考 tests.sh 的做法启动前先清理占用进程或改用不同端口--port配合API_URL同步修改。2. 测试结果被缓存E2E 测试依赖外部服务状态务必始终携带-count1否则 Go 可能直接返回上一次的缓存结果造成“测试通过但实际未执行”的假象。3. 函数注册失败或事件未触发检查INNGEST_SIGNING_KEY是否与 Dev Server 期望一致开发环境常为test以及SDK_URL是否准确指向 SDK 的/api/inngest端点。测试进程在init()中解析这些变量tests/main.go变量缺失或 URL 无 host 会直接 panic。4. Connect Gateway 行为异常但无日志先确认是否处于 dev 模式且未设置CONNECT_GATEWAY_FULL_LOGStrue——此时日志被VoidLogger丢弃pkg/connect/service.go并非程序没有输出。另外注意--log-level的全局级别也需足够低如trace才能看到详细内容。总结Inngest 的 E2E 测试链路清晰地划分为“本地 Dev Servercmd/devserver/cmd.go→ JS SDK 宿主tests/js→ Go 测试进程tests/main.go”三个部分由API_URL、SDK_URL、INNGEST_SIGNING_KEY等环境变量串联。掌握-test.run过滤、-count1防缓存以及CONNECT_GATEWAY_FULL_LOGS与--log-level trace的调试组合你就能高效地验证本地代码改动、精准定位失败用例并深入排查 Connect Gateway 的长连接问题。若需全自动执行仓库根目录的 tests.sh 脚本已封装完整的编排流程。【免费下载链接】inngestThe leading workflow orchestration platform. Run stateful step functions and AI workflows on serverless, servers, or the edge.项目地址: https://gitcode.com/GitHub_Trending/in/inngest创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考