insforge InsForge E2E Testing Gate
Use this skill after local implementation and normal InsForge pre-PR checks pass, and before opening, updating, or submitting the InsForge OSS PR.
This is an additional release-quality gate. It does not replace local typecheck, lint, test, or build validation from the parent insforge-dev skill.
Repositories
- InsForge OSS repo: current workspace.
- E2E repo: remote GitHub repository
InsForge/agent-e2e.
Use the remote InsForge/agent-e2e repository for workflow dispatch and read-only workflow checks. Do not rely on a developer-specific local checkout path. Create or use a local checkout only when the deterministic fixture tests must be edited.
Build The Test Tag
- Read the root InsForge
package.jsonversion. - Increment only the patch number.
- Build a tag in this form:
v<major>.<minor>.<patch+1>-<feature-or-issue-slug>
Example: root version 2.2.3 and feature storage returning rls becomes v2.2.4-storage-returning-rls.
Use the package.json version as the only source of truth for the base version. Ignore higher existing test tags when calculating the base version.
Slug rules:
- Prefer the issue key, PR topic, or branch topic.
- Lowercase all letters.
- Replace runs of non-alphanumeric characters with one hyphen.
- Trim leading and trailing hyphens.
- Keep it short enough to scan in GitHub Actions and image tags.
Build The InsForge Image
Dispatch the InsForge Build and Push Docker Image workflow with the test tag:
gh workflow run "Build and Push Docker Image" --repo InsForge/InsForge --ref <insforge-feature-branch> -f test_tag=<test-tag>
Then wait for the matching run to complete:
gh run list --repo InsForge/InsForge --workflow "Build and Push Docker Image" --limit 10
gh run watch --repo InsForge/InsForge <run-id>
Do not start the cross-repo E2E workflow until the image build succeeds.
Decide Whether agent-e2e Must Change
Inspect the InsForge diff and compare it with deterministic fixture coverage in InsForge/agent-e2e.
For read-only checks, prefer remote GitHub access such as gh api, gh repo view, or remote file reads. Use a local checkout only when editing fixture files or when remote inspection is not enough to understand coverage.
Update agent-e2e when the InsForge change adds, removes, or changes behavior that the deterministic fixture should assert, including:
- API contract or validation behavior.
- Auth, permissions, RLS, storage, realtime, functions, schedules, AI, SDK, or CLI-visible behavior.
- Any regression that local tests cover but the release gate should also protect across the deployed runtime.
Do not update agent-e2e for internal refactors, docs-only changes, local test-only changes, or behavior already covered by the deterministic fixture with no assertion change needed.
Ignore Support Desk Agent E2E (Exploratory). It is not part of this gate.
If No E2E Test Update Is Needed
Run the deterministic fixture workflow from agent-e2e main:
gh workflow run "Deterministic Fixture E2E" --repo InsForge/agent-e2e --ref main -f insforge_tag=<test-tag>
Find and watch the run:
gh run list --repo InsForge/agent-e2e --workflow "Deterministic Fixture E2E" --limit 10
gh run watch --repo InsForge/agent-e2e <run-id>
If E2E Tests Need An Update
Work in a local checkout of the remote InsForge/agent-e2e repo only for the fixture update.
- Use an existing clean checkout or clone
https://github.com/InsForge/agent-e2e.gitinto an isolated workspace. - Fetch
originand start fromorigin/main. - Create a branch named
codex/<short-topic>. - Update only the deterministic fixture validators, fixtures, app assertions, and docs needed for the InsForge behavior change.
- Run the smallest local validation that gives confidence:
npm run typecheck
npm run lint
npm run fixture:e2e:dry
Run broader validation when the changed fixture area supports it.
- Open an
agent-e2ePR for the fixture update. - Dispatch the deterministic fixture workflow from the
agent-e2ebranch that contains the fixture update:
gh workflow run "Deterministic Fixture E2E" --repo InsForge/agent-e2e --ref <agent-e2e-branch> -f insforge_tag=<test-tag>
- Watch the run before proceeding with the InsForge PR.
Interpret Results
If the deterministic fixture workflow passes:
- Link the run in the InsForge PR body or final PR notes.
- If an
agent-e2ePR was required, link that PR too. - Proceed with opening, updating, or submitting the InsForge OSS PR.
If the deterministic fixture workflow fails:
- Inspect the failed job logs and uploaded artifact.
- Identify whether the failure is caused by the InsForge implementation, the new or existing deterministic fixture, a transient infrastructure problem, or an unrelated existing failure.
- Fix the correct branch:
- InsForge implementation bug: update the InsForge branch, rebuild the test image with the same tag or a new short retry tag, then rerun E2E.
- Fixture bug or missing assertion update: update the
agent-e2ebranch, rerun local validation, then rerun E2E from that branch. - Transient infrastructure issue: rerun once after noting the evidence.
- Do not submit the InsForge PR until the deterministic result is clear or the user explicitly accepts the risk.
Report Back
When finished, report:
- Test tag used.
- InsForge image workflow run result.
- Whether
agent-e2echanged. - Deterministic Fixture E2E run result.
- Links to the InsForge PR,
agent-e2ePR if any, and workflow runs.