What TestingForge is (in one minute)

TestingForge is a web application for API-first automated testing. You connect your source code repository (GitHub or GitLab), point the product at the HTTP environments you already use (staging, QA, production-like sandboxes), and work with Bricks and Scenarios — structured steps that represent real API calls, variables, and assertions.

The product can generate and maintain suites over time, run them on demand or in CI, and surface clear run diagnostics when something fails. It does not generate browser UI end-to-end tests today — only HTTP/API flows.

Bricks — complete guide (and “Librix”)

In TestingForge, a Brick is one API call stored as a plain, editable database record — not a line buried in a generated script you cannot open. The Bricks page subtitle says it plainly: “Every API call your scenarios execute.”

If you have seen the name Librix in an older note, treat it as the same subsystem: Bricks in the UI at /workspace/bricks.

How pieces nest (read this once)

Think top → bottom, like a table of contents for your test run:

1. Workflow (called Scenario in the database) — e.g. “Checkout smoke”. This is what you pick on Run test and what CI passes as test_scenario_id.
2. Section (called Group) — e.g. CHECKOUT, CLEANUP. Sections run in order; use ⇅ Sort groups on the Bricks page to change that order.
3. API call (the Brick) — e.g. POST /login, GET /cart. Calls inside a section run in order; drag the ⋮⋮ handle to reorder.

Open the Bricks page

1. Log in and open Bricks (/workspace/bricks).
2. You see one block per workflow. If you have several, use the tabs under the search box (★ marks the default workflow).
3. Use the search field to filter by label, URL, or HTTP method. Keyboard: press / to focus search; ⌘K opens the command palette; ? shows shortcuts (when enabled in your build).
4. Each row is one brick: method badge, label, URL template, optional health badge (% success on recent runs), and ✎ Edit.

Anatomy of one brick (every field, in plain language)

Click ✎ Edit on any row. The editor is split into a main form (left) and preview / Try it / revisions (right). Core fields:

• Method — GET, POST, PUT, PATCH, DELETE, etc.
• URL template — path such as /api/v1/orders/{orderId}. Placeholders in curly braces are filled at run time.
• Host — Use run environment (default): the base URL comes from the domain you pick on Run test ({baseUrl}). Custom host: call another service — paste https://files.example.com or {option.STORAGE_HOST}; the URL template path is appended.
• Kind — usually http_request. Advanced kinds include auth_login, http_poll_until (retry until a status appears), sleep, assert, file upload helpers, and org-specific hooks. Pick the kind that matches what the runner should do, not just “another GET”.
• Label & description — human names for the index and for debugging failed runs.
• Tags — comma-separated labels (e.g. auth, smoke) for your own organisation.
• Auth profile — tells the runner which headers/tokens to attach automatically (e.g. bearer token, re-login on 401, anonymous SPA). Profiles like none mean you manage headers manually.
• Body mode — none, json, form_params, multipart, or raw. The runner sets Content-Type appropriately; do not fight it with duplicate Content-Type headers unless you know why.
• Body template — JSON or text with {placeholders}, e.g. {"email":"{option.E2E_USER_EMAIL}"}.
• Headers — extra name/value pairs; values support {variables}. Override auth profile defaults when names collide.
• Allowed / warn statuses — which HTTP status codes count as pass vs warning (comma-separated lists in the form).
• Timeout (seconds) — per-call ceiling (1–3600).
• Flags — active (skip when off), advanced, optional (scenario continues even if this brick fails).

Variables — how data flows between bricks

At the top of the editor, coloured chips show variables you can click to insert at the cursor:

• Runtime — built-ins such as {baseUrl}, {runId} (provided by the runner for every run).
• Upstream — values produced by earlier bricks in the same workflow via Extracts.
• Org option — {option.KEY} from organisation settings or the Secrets vault (encrypted options). Example: {option.E2E_USER_EMAIL}.
• This brick — names you define in Extracts on this brick; downstream bricks can use them after this brick runs.

Extracts (in the editor) — after the HTTP response arrives, copy a value into a variable:

• variable_name — e.g. token → later bricks use {token}.
• source — json_path (field in JSON body), header, status, or url_path.
• expression — e.g. data.attributes.token for JSON.
• required / default — fail fast if missing, or fall back to a default string.

Checks (response assertions) — evaluated after the call. If any active check fails, the brick fails:

• Target — JSON path, raw body, or response header.
• Operator — equals, contains, regex, not_empty, empty, etc.
• Expected value — can include {variables} before comparison.

Conditions — optional gates: skip or run the brick only when a variable matches a rule (useful for branching without duplicating whole workflows).

On the Bricks index, a red ⚠ unresolved badge means a {name} is referenced but nothing upstream, no org option, and no runtime var provides it yet — fix extracts or add an org option before relying on the run.

Editor actions you should know

1. Save — every save creates a revision. Scroll to Revision history on the right and revert to an older revision if you break something.
2. Try now — fire this single brick against a chosen environment with optional variable overrides; use this before running the whole workflow.
3. Compare with template — if your brick was forked from a shared baseline, see the diff vs upstream and optionally sync changes.
4. duplicate — clone the brick inside the same section.
5. Request preview — right panel shows the rendered URL/body with sample variables before you hit the network.

Import — don’t type what you already have

From a workflow header on the Bricks page:

• ↓ Import cURL — paste a command from Chrome DevTools, Postman, or terminal (/workspace/bricks/import). You land in the editor with fields pre-filled; fix extracts and checks next.
• ↧ Import bulk — paste Postman Collection v2.x or OpenAPI 3.x JSON (/workspace/bricks/import/bulk). One brick per operation. Template sections are auto-forked to your org when needed.
• + Add API call inside a section — blank brick appended to that group.
• ＋ New workflow — cherry-pick existing API calls from any workflow into a new org-owned copy (/workspace/bricks/scenarios/create).

Templates, customization, and “amber” sections

Many orgs start from a shared template workflow shipped with their driver. You will see:

• Plain sections — still the shared default.
• Amber / “customized” sections — your org forked the group; edits are yours.
• Counter on the page: “X customized by you” — how many forked/custom bricks you maintain.

Important buttons:

• ⟲ Revert to default on a customized section — drops your fork and restores the shared baseline (destructive; confirm the dialog).
• ★ Set as default on a workflow — the one pre-selected on Run test and the usual target for CI snippets.
• ✕ Delete workflow — only for workflows your org created (or empty orphans); past runs stay in history.

Health badges on each row (e.g. 95% · 120ms) summarise recent run outcomes for that brick — click through to the last failing run when available.

More marketing context and UI mockups: Bricks product page.

Account, organization, and roles

Create an account (click by click)

1. Open the TestingForge homepage and look at the top-right of the navigation bar.
2. Click Register. If you are on a phone, open the “hamburger” menu (three horizontal lines) first — the same links are inside the mobile menu.
3. Fill every required field. Password managers (1Password, Bitwarden, iCloud Keychain, etc.) are encouraged — you will reuse this login often.
4. Submit the form. If the page shows an error in red, read it literally: duplicate email, weak password, or network issues are the usual causes.
5. Go to your email inbox, find the verification message, and click the link inside. Details in the next section.
6. Return to the site and click Log in with the same email and password.

Organization

Work in TestingForge happens inside an organization. Billing, repositories, domains, and runs belong to the org. If someone invited you, accept the invite link from the email; your user will join their organization.

Roles (who can click what)

Common roles include Owner, Automated QA, and Runner. Owners manage billing and integrations. Automated QA typically sets up repositories, environments, and bricks. Runner can execute tests that are already configured. If a button is disabled or missing, your role may not include that action — ask an Owner in your org.

Inviting teammates

Organization owners invite colleagues from Organization members (/organization/members). Invited people receive a link; until they accept, they do not consume a seat in your plan.

Email verification (why the app blocks you)

After you register, Laravel-style email verification protects the workspace: you can authenticate, but protected routes keep redirecting you until the verification link is clicked.

1. Check spam/junk if nothing arrived in two minutes.
2. Click the verification button or URL in the email — it must open in a normal browser session (not an embedded in-app browser that strips cookies, if you can avoid it).
3. Log in again if the session expired during the round trip.
4. You should now reach Dashboard or onboarding without “verify your email” banners.

Where things live in the app (URL map)

Replace https://testingforge.io mentally with your deployment host. Paths below are the ones Laravel registers in this repository — bookmark them once you are logged in.

• /dashboard — Dashboard.
• /onboarding — Onboarding checklist.
• /repositories — Repositories + SCM token + per-repo CI snippets.
• /domains — Domains / environment targets.
• /environments — Alternate environments UI (same domain model; use whichever your org adopted).
• /secrets — Secrets vault.
• /workspace/bricks — Bricks and scenarios index.
• /test-launch — Manual “Run test” launcher.
• /ci-notifications — CI API key + Slack-style notifications.
• /logs — Logs.
• /reports — Reports.
• /billing — Billing.

First run checklist (onboarding)

After you log in, open Onboarding if the app sends you there. The checklist is deliberate — each step unlocks the next.

1. Connect SCM — Link GitHub or GitLab with a personal access token (PAT) or OAuth, depending on what the Repositories screen offers. A PAT is just a long random password GitHub/GitLab shows once — paste it into TestingForge immediately and store a copy in your team vault if policy requires. Until the platform can read repository metadata, generated context and some shortcuts stay empty.
2. Add domains — Under Domains, create domain groups and add the hosts you are allowed to hit (for example https://api.staging.example.com). This is how you tell TestingForge where HTTP requests may go.
3. Activate billing — Pick a plan on the Billing page so production runs and quotas align with your subscription. Until billing is active, runs may stay blocked even if everything else is configured.
4. Start testing — Open Run test (/test-launch), choose environment + scenario, and launch.

Repositories and GitHub / GitLab access

Open Repositories from the workspace navigation. This page is the control room for source control.

Connect a token (typical path)

1. While logged in, open Repositories (/repositories).
2. Scroll to the token / connect section (onboarding may deep-link you to #connect-token — the fragment scrolls the page for you automatically).
3. Create a PAT in GitHub or GitLab with the scopes suggested on the page (read repository metadata; never grant more than your security policy allows).
4. Copy the token string in full (usually starts with ghp_ on GitHub or glpat- on GitLab — prefixes change over time, always copy exactly).
5. Paste into TestingForge, click save/submit, wait for the success banner.
6. Use Refresh repositories. If the list is still empty after thirty seconds, reload the page once, then re-check provider status pages for API outages.

Why this matters

Repository access lets TestingForge map your project to endpoints, OpenAPI or code-derived hints, and CI wiring. Without it, you are limited to manual brick authoring and fewer guardrails.

CI snippets live here

Under each linked repository, expand CI/CD setup for this repository. You will see ready-to-paste GitHub Actions or GitLab CI YAML that references your test_scenario_id and the TF_API_KEY secret. More detail in the CI section below.

Domains and environments

A domain entry is a concrete base URL plus metadata (such as which environment name it represents). When you launch a run, you pick one of these domains so bricks hit the right cluster.

Add a domain (step by step)

1. Open Domains (/domains).
2. Create a domain group if you separate “Customer API” vs “Internal API”, etc.
3. Add a host URL. Include the scheme (https://). “Scheme” means the part before :// — without https:// the browser cannot speak TLS to your API.
4. Double-check trailing slashes only if your API is sensitive to them — some gateways treat /v1/users and /v1/users/ differently.
5. Return to Run test and confirm the host appears in the environment dropdown.

Secrets and org options

Sensitive values (passwords, API keys, client secrets) belong in Secrets (/secrets). They are stored encrypted; the UI never shows the plain text again — only masked previews.

In bricks, reference them as org options: {option.YOUR_KEY} in URL templates, headers, or body. The same keys can be set in non-secret organisation settings when the value is not sensitive.

1. Open Secrets and create a key, e.g. E2E_USER_PASSWORD.
2. In a brick body, write {"password":"{option.E2E_USER_PASSWORD}"} (or use the variable chip picker in the editor).
3. Use Rotate when the credential changes; update any external systems that still hold the old value.

Workflows (scenarios) — quick reference

A workflow is the full story your run executes. Everything about individual API calls lives in the Bricks guide above; this section is only workflow-level actions.

Create or change workflows

1. ＋ New workflow on the Bricks page — pick a source workflow, tick the API calls you want, name the copy. Originals stay untouched.
2. ＋ Add section on a workflow header — creates an empty group (then use + Add API call inside it).
3. ★ Set as default — pre-selects this workflow on Run test and is the usual CI target.
4. ⇅ Sort groups — reorder sections; bricks inside each section keep their own order.
5. ◇ Flow graph — visual map of the workflow; click a brick node to open its editor. Use Run workflow (dry-run) on the graph page to validate without a full billed run.

CI references a workflow by numeric id: test_scenario_id. Copy the exact value from Repositories → CI/CD setup — do not guess from the UI label alone.

If Run test shows no scenarios, your org may not have a provisioned driver yet, or workflows were removed. Finish onboarding (SCM + domains + billing) or create a workflow via import / ＋ New workflow.

Launching a test from the workspace

The Run test page (sometimes labeled Test launch) is the manual trigger panel.

1. Choose the environment (domain) you configured.
2. Choose the test scenario / workflow from the dropdown. Each option maps to a concrete test_scenario_id used by CI as well.
3. Confirm driver / repository side settings if the page shows them — some workspaces attach a repository connection for richer runs.
4. Click Run (or the primary action button). If the button stays disabled, read the inline message: usually a missing environment, scenario, or subscription state.

Runs, reports, and logs

After you start a run, TestingForge records a run record: status, counters, timeline, and per-request traces for debugging.

• Open Dashboard for a high-level snapshot.
• Use Logs or run history pages (exact labels depend on your build) to find a failed run.
• Open the report link on a run to see assertion-level detail — which brick failed, which HTTP exchange broke, and what response body came back.

When a run fails, fix either the system under test (real bug) or the brick expectations (intentional API change). If the platform proposes self-healing updates, review the diff before accepting — you stay in control of what merges into the suite.

CI/CD and TF_API_KEY

Continuous integration should call TestingForge the same way a human would from Run test, but non-interactively.

1. Open CI & Notifications (or the CI section inside Repositories, depending on your version).
2. Generate or copy the CI API key. In pipelines, store it as a secret named TF_API_KEY — the YAML snippets assume exactly that name.
3. Copy the workflow snippet from Repositories → your repo → CI/CD setup. It includes the HTTP call shape and the test_scenario_id for the scenario you selected.
4. Commit the workflow file, push, and watch the pipeline start a run. Poll until the run completes and surface the report URL in your own logs if desired.

Cursor MCP (IDE integration)

The workspace CI API key (TF_API_KEY) powers CI, the Machine API, and hosted MCP for Cursor. Endpoint: https://testingforge.io/mcp/server — no Node, no ZIP. Setup: /mcp or CI & Notifications in the app.

1. Generate or copy tf_… in CI & Notifications.
2. export TF_API_KEY='tf_…' in terminal; launch Cursor from that terminal (or add to ~/.zshrc).
3. Use app/.cursor/mcp.json in the repo, or copy JSON from /mcp into ~/.cursor/mcp.json.
4. Enable testingforge under MCP settings; quit and reopen Cursor.
5. In Agent: mcp_guide, workspace_list_bricks, workspace_start_run, machine_api_routes.

Pulse (load-style checks)

Pulse is a separate marketing and product surface for hammering a single endpoint many times with a simple wizard — useful for quick “is this route stable under burst?” intuition without standing up k6 or JMeter locally.

Read the dedicated page for behavior and limits: Pulse.

Live demo workspace

The Live demo route hosts a public, reset-on-a-schedule workspace with a sandbox API and credentials printed on the page. Use it when you want to click through bricks and runs without creating an account first.

Billing and quotas

Plans and entitlements live under Billing. If runs refuse to start, verify:

• Subscription status is active (payment method valid, no expired trial).
• Monthly run quota is not exhausted.
• Your user still belongs to the intended organization (check org switcher if present).

Troubleshooting

OAuth or token errors

Confirm callback URLs in your Git provider match the values configured for this deployment (services.php / environment on the server). Regenerate the PAT if scopes were too narrow.

Empty repository list

Re-save the token, refresh repositories, and verify the PAT owner actually has access to the org/repos you expect.

Run stuck or immediately failed

Check worker and application logs (operators: see project README for docker compose logs). Common causes: wrong domain URL, SSL interception, auth secret missing, or scenario referencing deleted bricks.

Brick / variable issues

Open the brick editor and check the right panel for ⚠ Unresolved variables. Add an Extract on an earlier brick, set an org option / secret, or supply a Try now override while debugging.

If import into a template section fails with “fork it first”, use bulk import (auto-forks) or edit a brick in that section once — customizing creates your org’s copy automatically.

CI cannot start runs

Ensure TF_API_KEY is present in the CI secret store for that repository, not only on your laptop. Re-copy the snippet after changing the default scenario id.

Cursor MCP

See MCP troubleshooting in the MCP section, or the copy-paste blocks on /mcp and CI & Notifications.

Glossary

• Brick — One API call record: method, URL, headers, body, extracts, checks, auth profile.
• Librix — Informal name for the Bricks subsystem; in the product UI always use Bricks.
• Workflow / Scenario — Top-level test story; picked on Run test; CI uses test_scenario_id.
• Section / Group — Named block inside a workflow (e.g. CHECKOUT); runs before later sections.
• Extract — Rule that copies a response value into a variable for downstream bricks.
• Check — Assertion on response JSON, body, or headers; failure fails the brick.
• Org option — Key/value on the organisation, referenced as {option.KEY} in templates; secrets use the same syntax but are encrypted.
• Fork / customized — Your org’s editable copy of a shared template section (amber badge in the UI).
• Domain — Allowed base URL (environment target) for runs; becomes {baseUrl}.
• Workspace — Authenticated app where you manage bricks, runs, and integrations.
• TF_API_KEY — Workspace CI API key for pipelines.
• Self-healing — Proposed updates to bricks when APIs drift; human review before merge.

Questions not covered here: Contact the team or your internal TestingForge admin.