Nocticas

Nocticas E2E 门禁 — GitHub Action

每次推送或 PR 时，针对目标 URL 运行固定的 Nocticas 门禁，并在判定为红色时使构建失败。浏览器运行在 Nocticas 的服务器上——此 Action 是一个轻量客户端，用于启动运行、轮询判定结果，并将其映射为退出代码。杜绝假绿：运行框架出错绝不会被视为通过。

快速开始

1. 在 Nocticas 中创建并固定流程（运行 Agent → 固定 → 将确定性步骤脚本导出为 JSON）。
2. 将门禁文件提交到仓库，例如 .nocticas/checkout-flow.json。
3. 将密钥添加为仓库 Secret：NOCTICAS_API_KEY。
4. 添加工作流：

# .github/workflows/nocticas.yml
name: Nocticas E2E gate
on: [pull_request, workflow_dispatch]
jobs:
  verify:
    runs-on: ubuntu-latest          # standard runner = free on public repos
    steps:
      - uses: actions/checkout@v4   # so the gate file is available
      - uses: Low-Latency-Labs/nocticas-action@v1
        with:
          api-key: ${{ secrets.NOCTICAS_API_KEY }}
          gate: .nocticas/checkout-flow.json
          target: ${{ vars.PREVIEW_URL }}   # your deployed preview/staging URL

判定为红色会使任务失败 → 阻止 PR 合并。

输入

输入	必填	默认值	说明
api-key	是	—	Nocticas API 密钥（请将其存储为 Secret）。
gate	是	—	仓库中固定门禁 JSON（确定性步骤数组）的路径。
target	是	—	要测试的 URL（例如 PR 的预览部署）。
api-base	否	https://app.nocticas.com/api	Nocticas API 基础地址。
timeout-seconds	否	300	等待判定结果的最长时间。
poll-seconds	否	3	轮询间隔。
fail-on-error	否	true	将运行框架的 error（而非测试失败）视为构建失败。未经验证的运行绝不会被视为通过。

输出

输出	说明
run-id	Nocticas 运行 ID（可在日志中附上链接）。
verdict	passed | failed | error | timeout。

门禁文件

一个由确定性步骤组成的 JSON 数组——正是 Nocticas 在你固定一次通过的运行时生成的内容。示例见 examples/gate.example.json。将它保存在仓库中，就能让 E2E 测试与其所保护的代码一同进行版本控制。

**请勿提交真实凭据。**将门禁指向暂存或预览环境，并使用专用测试账户；Nocticas 内置的测试收件箱可处理 OTP／魔法链接登录，因此你无需将密钥嵌入门禁文件。

费用

• **发布此 Action：**免费（公开仓库，无需付费计划）。
• **运行此 Action（你的客户）：**在公开仓库中使用标准运行器免费；在私有仓库中则计入每月免费分钟额度。它只有一个轻量任务，仅占用数秒运行器时间。
• 浏览器运行：使用 Nocticas 积分计费——而且确定性／固定运行在每月额度内免费，因此每次推送都运行门禁通常不会消耗积分。

其他 CI 系统（实现方案）

不使用 GitHub？同样的“启动 → 轮询 → 退出”逻辑可以用可移植脚本实现——请参见 recipe.sh 和 examples/gitlab-ci.example.yml。交互约定就是通过 HTTP 传输 JSON：

POST {api-base}/runs   { "mode":"deterministic", "target": "...", "script": [ ...gate... ] }   → { "id": "..." }
GET  {api-base}/runs/{id}                                                                       → { "status": "passed|failed|error|..." }

请求头：x-nocticas-key: <key>。除非 status == "passed"，否则以非零状态退出。