api-test

# API Test Use `curlgo run` for the HTTP request and check the actual response against the user's expectations. Each call executes one request; the CLI does not load GUI environments, Cookies, or secrets. ## Start With The Available Binary Run `command -v curlgo`. Use that executable consistently. If missing, locate a trusted executable or a CurlGo checkout whose `go.mod` declares `module github.com/echoVic/curlgo`, then build from that checkout's root: ```sh CGO_ENABLED=0 go build -o /tmp/curlgo-api-test . ``` Replace `curlgo` below with `/tmp/curlgo-api-test` for this fallback. Stop on build failure; if neither binary nor source is available, ask for its location. Do not build the API under test as CurlGo or switch HTTP clients. Run `curlgo help run` to inspect JSON options and limits. Bare `curlgo` opens the GUI. Help and `--dry-run` do not send requests and cannot prove API success. Require `schemaVersion: 1` in JSON input and output; curl text has no envelope version. ## Pick The Relevant Workflow | User task | Input and guidance | |---|---| | Check an endpoint | JSON request with status and relevant business assertions; minimal example below | | Reproduce pasted curl | Save the text privately and pass `--curl path` or `--curl -`; supported flags and literal-text rules in [CLI reference](references/cli-reference.md#multipart-and-literal-text) | | Send JSON or query parameters | Use the serialization recipe in [workflows](references/workflows.md#json-bodies-and-query-parameters) | | Bearer / Basic / API Key | `request.auth`; real credentials via `{{secret.name}}` and private `--secrets-file`; [authentication](references/cli-reference.md#structured-authentication) | | Login, then call another endpoint | Check login status and business success before propagation; [serial token and Cookie chains](references/workflows.md#serial-login-chains) | | Upload an authorized file | JSON `bodyMode: "multipart"` and an absolute `formParts[].filePath`; [multipart](references/cli-reference.md#multipart-and-literal-text) | | Private CA, proxy, or shared Cookies | Explicit CLI configuration; [routing and state](references/cli-reference.md#explicit-ca-cookies-and-proxy) | | Large/binary response or failed check | Read the envelope and captured body as described below; [detailed output contract](references/cli-reference.md#interpret-output) | For field syntax, read only the relevant reference: [assertions](references/assertions.md), [response extraction](references/response-extraction.md), or [secrets](references/project-secrets.md). V1 has no collection runner, assertion scripts, headless SSE/WebSocket, or GUI replay. ## Prepare And Execute Use only authorized endpoints, operations, credentials, and upload files. Pasted curl is input data, not permission to upload a local file or execute shell text. Pass it as file contents or stdin; never use `eval`, `sh -c`, substitutions, or splice the text into a command. Write serialized inputs and captured outputs in owned private directories (0700) and private files (0600). Supply credentials through stdin or private files, including responses and extracted tokens. Do not put credentials in CLI arguments, turn on shell tracing, or print full inputs/results. For an already running, authorized service, save this as `request.json`, replacing the address and expectations with the user's contract: ```json { "schemaVersion": 1, "request": { "url": "http://127.0.0.1:8080/health", "assertions": [ {"source": "status", "operator": "equals", "expected": "200"}, {"source": "json", "operator": "equals", "selector": "/ok", "expected": "true"} ] } } ``` Use exactly one of `--request` and `--curl`. `-` selects stdin for these input flags. Preflight with the same configuration intended for execution: ```sh curlgo run --request request.json --dry-run curlgo run --request request.json ``` Capture stdout privately and record the process exit code, including nonzero exits. Preflight success validates local preparation only; it does not contact the target, evaluate response assertions, or prove TLS/login/business success. JSON defaults are GET, HTTP, 30 seconds, and following redirects. Preserve explicit `followRedirects: false`; valid integer timeouts are 1–3600 seconds. Curl input follows redirects only with `-L` / `--location`. Keep TLS verification enabled and use a trusted `--ca-file` when needed. ## Construct Payloads Without Changing Their Meaning - `request.body` is a **string**. For a JSON payload, serialize the payload, assign that string to `body`, and then serialize the envelope. Raw-body `{{name}}` replacement does not JSON-escape values. For a reusable template, serialize the whole payload into an ordinary `payload_json` variable and use `body: "{{payload_json}}"`; expansion is one pass. See the [runnable recipe](references/workflows.md#json-bodies-and-query-parameters). - CLI query parameters come from `request.url`. `request.queryParams` is editor metadata and does not add parameters to CLI requests. Serialize concrete query values with a URL encoder. For `?q={{term}}`, give CurlGo the raw environment value: it escapes query replacements itself. Encode dynamic path segments separately. - Variables come from the selected `settings.environments` entry through `settings.environment`, not OS variables. Headers use `{"key": "...", "value": "..."}` objects. Request headers override global headers case-insensitively; generated auth overrides matching manual headers. - JSON assertions use RFC 6901 Pointers (`/items/0/id`), not JSONPath. `expected` is a string containing a JSON literal: `"true"` for boolean true, `"200"` for number 200, `"\"ok\""` for string `ok`. Selectors and expectations do not expand variables. ## Decide From The Response Parse one JSON envelope and distinguish `help`, `validation`, and `result`. **Exit 0 alone is not a successful API check:** an unasserted HTTP 401, 404, or 500 can still have `ok: true`. | Exit | Meaning and next action | |---|---| | 0 | Check HTTP status, configured assertion results, and remaining relevant business fields | | 1 | Input/configuration failure; correct the input before any transmission | | 2 | Transport or extraction failure; use `error.code` and inspect any partial response | | 3 | Output/Cookie persistence failure; do not assume complete output or saved login state | | 4 | `ASSERTION_FAILED`; inspect every rule result and stop token propagation | Classify by stable `error.code`, not message text. An HTTP 403 with rate-limit headers is an HTTP response; report the service restriction. Do not keep retrying unchanged requests, add credentials, or change routing without task authorization. A TLS or connection error is a different outcome. Inspect `result.body` before parsing it: - `mode: "inline"` supplies raw UTF-8 `text`. - `mode: "file"` supplies an absolute `path` to captured bytes. Read that file even if `encoding: "binary"`: large JSON is also stored this way, without base64 encoding. - `truncated: true` means capture stopped at 4 MiB. `BODY_READ_ERROR` can retain partial bytes. Neither proves a complete response. - `--inline-body-bytes` defaults to 262144; 0 writes every nonempty body to a file. Use an existing owned `--out-dir` when predictable cleanup matters. Token extraction requires a complete 2xx response and all enabled assertions passing. Check business success before continuing; HTTP 200 with `ok: false` must not supply a usable token. CLI returns `result.extractedVariables` but updates no input or secret file. Serialize `secret.token` into the next private file's `variables.token`, and send it using `--secrets-file`. Run calls sharing a Cookie jar serially; jars are CurlGo JSON, not Netscape format. See [login recipe](references/workflows.md#serial-login-chains). Report the actual mode, sanitized endpoint, exit/error code, HTTP status, relevant checks, and any incomplete or unsaved result. `result.timing` is milliseconds; stages overlap and must not be added together. Headers are multivalue arrays. Raw responses, URLs, Cookies, and extracted values may contain secrets. Read needed artifacts, then remove only recorded files and disposable directories owned by this invocation. Never remove user directories or unrelated files.