Nodexa - API Testing in VS Code

Version 1.1.0 | Extension ID: nodexa.nodexa | VS Code 1.95+

Create, send and test HTTP requests without leaving VS Code. Organize JSON collections, chain requests in visual flows, run data-driven suites and measure concurrent flow workloads with local environments and Git-friendly files.

No separate app. No sync account. Your definitions live in your workspace.

Index

1. Why Nodexa?
2. Quick Start
3. Views
4. Request Editor
5. Authentication
6. Environments, Variables And Secrets
7. Visual Flows
8. Assertions
9. Pre-request And Post-response Actions
10. Test Suites And Load Tests
11. JSON Datasets
12. History And Reports
13. Import, Export And Compatibility
14. File Layout
15. Safety And Limits
16. Requirements
17. Troubleshooting
18. Support
19. Development From Source
20. Roadmap
21. Documentation

Why Nodexa?

• Stay in VS Code: collections, request tabs, responses, flow properties and test results in your editor.
• Review changes in Git: requests, flows, suites, load plans and non-secret datasets are ordinary JSON files.
• Test complete workflows: reuse earlier responses, extract variables, branch, loop, retry and poll.
• Separate positive and negative scenarios: override request payloads and assertions per flow without changing shared requests.
• Use data-driven tests: select JSON datasets and run ordered suites or isolated concurrent flow iterations.
• Inspect results: assertion outcomes, HTTP latency, throughput, error rates and redacted metadata reports.
• Keep execution local: no Nodexa cloud backend, account, sync service, analytics or telemetry.

Quick Start

1. In VS Code's Extensions view, choose Install from VSIX... and select the supplied Nodexa 1.1.0 package.
2. Open a local folder or workspace and trust it before writing definitions or sending requests.
3. Run Nodexa: Initialize Collections from the Command Palette.
4. Set your API's baseUrl and credentials in the selected local environment.
5. Open Nodexa: Open API Client, select a request, review it and choose Send.
6. Use Nodexa: New Flow, Nodexa: New Test Suite or Nodexa: New Load Test for repeatable workflows.

Cmd/Ctrl+Enter sends a request; Cmd/Ctrl+S saves while the request editor is focused. Initialization creates missing examples only and does not start an API server.

This is a locally packaged release. A Marketplace listing and publishing are separate steps; this document does not claim an existing listing.

For an existing installation under the previous name, stop runs and save drafts before renaming its shared definitions folder to nodexa/ and its local environment folder to .nodexa/. Preserve file contents, never overwrite an existing destination, and Git-ignore .nodexa/. Install Nodexa, remove the old extension if both appear, reload and reselect the intended environment. Extension-scoped history and environment selection are not automatically migrated. The detailed guide in docs/README.md contains the complete upgrade steps.

Views

The Nodexa activity bar contains four sections:

Environments are selected and managed through the request editor's environment controls and Nodexa: Manage Environments. They are not a separate activity-bar view. History is local request-summary storage, not a replayable snapshot archive. There is no Credentials or WebSocket view in this release.

Request Editor

Edit method, URL, query parameters, headers, authentication, body, tests, pre-request actions and post-response actions. Supported HTTP methods are GET, POST, PUT, PATCH, DELETE, HEAD and OPTIONS.

• Open multiple request tabs and browse nested collections.
• Send the current draft, save its JSON definition or open the source in VS Code.
• Use JSON objects/arrays as bodies or strings as raw text; GET and HEAD cannot have bodies.
• Inspect status, elapsed time, response size, pretty/raw body text, headers and test outcomes.
• Cancel active requests and copy response text.
• Copy a redacted, shell-quoted cURL command using the code icon beside Save.

Example collection request:

{
  "name": "Create User",
  "method": "POST",
  "url": "{{baseUrl}}/users",
  "headers": { "Content-Type": "application/json" },
  "auth": { "type": "bearer", "token": "{{accessToken}}" },
  "body": { "name": "{{name}}", "requestId": "{{uuid}}" },
  "tests": [
    { "type": "status", "expected": 201 },
    { "type": "json-path", "path": "$.id", "exists": true }
  ]
}

Provide name through an environment, a dataset or an earlier action. Headers and parameters are string maps; duplicate keys are not supported. Unsaved drafts are not automatically replaced by external file changes.

Authentication

OAuth token acquisition, Digest, OAuth 1.0/2.0 flows, AWS SigV4, NTLM, Hawk, WSSE and client-certificate authentication are not implemented. Declarative HMAC actions generate values; they are not full authentication-protocol implementations.

Environments, Variables And Secrets

Each local environment is a JSON file under .nodexa/env/. For example:

{
  "variables": {
    "baseUrl": "http://localhost:8080",
    "name": "Jane"
  },
  "secrets": {
    "accessToken": "replace-with-your-local-token"
  },
  "protected": false
}

The filename determines the environment name. Select it in the editor and use placeholders such as {{baseUrl}}, {{name}} and {{accessToken}} in request strings.

• Use the plus control to add an environment and the key control to enter a secret through a masked native input.
• The environment menu offers local configuration editing, environment creation, secret setting and secret removal.
• Secrets take precedence over ordinary variables, including dataset values with the same name.
• {{uuid}} and millisecond {{timestamp}} are built-in reserved variables.
• Missing variables cause an error instead of sending unresolved placeholders.
• Environment names containing prod are protected by default unless explicitly overridden.

Secrets are plaintext in environment files, not encrypted or stored in the OS keychain. The extension Git-ignores .nodexa/ and excludes it from packages. Protect local files and backups; .gitignore does not remove credentials already tracked in Git.

Visual Flows

Drag nodes onto the canvas or add them with palette buttons. Connect output dots to input dots, select nodes to edit Properties, and save the graph under nodexa/flows/.

Controls are smaller than request boxes. Scroll up to zoom in and down to zoom out on the canvas, within 40%-160%; Properties and run-log scrolling stay independent.

Execution badges show a green circle with a tick for success, a red circle with a cross for failure and a spinning loader inside a circle while processing. Waiting, retrying and stopped states are also shown. Reduced-motion preferences disable spinning.

Dependencies And Conditions

Request nodes reference collection-relative filenames. An extraction such as extract: { "userId": "$.id" } exposes {{userId}} and {{vars.userId}} later in the same run. Full dependencies can reference earlier executed nodes, for example {{responses.create.body.id}}.

Conditions use bounded JSON Logic over env, vars, responses, loops and scoped error:

{ "===": [{ "var": "responses.lookup.status" }, 200] }

Branches, Loops And Error Handling

Connect every output before running. Outputs have one next node; multiple incoming edges are allowed. A loop body must connect back to its loop node, and the exit output must continue to the next step.

Ordinary paths execute in order; Parallel starts isolated branches and its selected Join waits for all of them, even if one fails. Outputs are namespaced under responses.<joinId>.body.branch1.vars and .responses (then branch2, etc.), not silently merged into parent state. Use Transform to explicitly select a joined value. Dependencies must already exist in the active scope.

Retry, Timeout and Finally have body/done outputs: return the body to its owning node, then continue through done. Retry defaults to two additional attempts and restores run-local data between attempts, not HTTP side effects. Timeout aborts scoped work before error routing. Parallel selects joinId in Properties and every branch returns to that Join; Join has one next continuation.

Try selects finallyId; its body and catch routes converge at that Finally. The catch output must start with a Catch node. Catch and Finally can read error.nodeId, error.code, redacted error.message and optional error.status. Fatal budgets and global cancellation bypass Catch. Finally executes once; an expired enclosing scope gets a one-second cleanup window, and global Stop/deadline disables all new cleanup HTTP requests. Request retry/polling/continueOnError policies remain compatible.

Display evaluates value, redacts known secrets and truncates the log value at 64 KiB. Transform evaluates every assign expression against the pre-transform state and writes string or JSON-encoded values under vars; it does not edit environment files or run JavaScript.

Use separate positive/negative graphs with request-level payload and test overrides. An explicitly expected 400 response can pass its assertions; otherwise non-2xx fails by default. Overrides do not modify the shared request file.

Use Run to execute and Stop to cancel requests, polling, retries and waits. Save before closing: drafts and results are not durable panel state.

Assertions

The Tests tab edits a declarative JSON array:

[
  { "type": "status", "expected": 201 },
  { "type": "duration", "maxMs": 1000 },
  { "type": "header", "name": "content-type", "exists": true },
  { "type": "json-path", "path": "$.id", "exists": true },
  { "type": "schema", "schema": { "type": "object", "required": ["id"] } },
  { "type": "condition", "condition": { ">": [{ "var": "body.id" }, 0] } }
]

Header names are case-insensitive. JSONPath supports existence and structural expected-value comparisons, with script evaluation disabled. Schema checks use inline draft-07 JSON Schema without remote fetching or format validation. Conditions use bounded JSON Logic, not JavaScript callbacks.

Pre-request And Post-response Actions

Actions are declarative JSON, not Bruno or Postman scripts:

{
  "preRequest": [
    { "type": "set", "name": "name", "value": "Jane" },
    { "type": "timestamp", "name": "sentAt" },
    { "type": "uuid", "name": "requestId" },
    { "type": "random-token", "name": "nonce" },
    {
      "type": "hmac-sha256",
      "name": "signature",
      "key": "{{signingKey}}",
      "value": "{{nonce}}"
    }
  ],
  "postResponse": [
    { "type": "extract", "name": "userId", "path": "$.id" },
    {
      "type": "extract",
      "name": "sessionToken",
      "path": "$.token",
      "secret": true,
      "required": false
    }
  ]
}

Actions run in order and can reference earlier values. Extractions are required by default. Values carry between requests within a flow or sequential suite, but are not written back to environment files or shared with other manual tabs.

Use secret: true for sensitive aliases. Random-token/HMAC outputs and token/signature/password-like aliases are automatically masked. Keep signing keys in environment secrets. Arbitrary JavaScript, bru.* and pm.* execution are not supported.

Test Suites And Load Tests

Create plans from their sidebar sections or the Command Palette. Import saved entries using the native picker, then save the plan.

The editor follows Input -> Flow -> Result:

• Input: select a JSON dataset, refresh available files or open its source.
• Flow: import entries, reorder them or remove entries.
• Result: inspect status and metrics, navigate to the report and export metadata.

Example load plan:

{
  "version": 1,
  "mode": "load",
  "name": "User workflow load",
  "entries": [{ "type": "flow", "file": "users.json" }],
  "dataset": { "type": "json", "file": "users.json" },
  "iterations": 2,
  "concurrency": 4
}

The flow entry above requires a separately saved flow with that filename. A suite uses mode: "suite" and concurrency 1. Every row-iteration runs all entries in order. Every load run requires confirmation; Stop cancels it.

JSON Datasets

Save a JSON array of non-secret objects under nodexa/dataset/:

[
  { "name": "Jane", "role": "admin" },
  { "name": "Taylor", "role": "viewer" }
]

Row keys become template variables. Non-string values are encoded as JSON strings. Iterations repeat the entire dataset, not just one row. Input values overlay ordinary environment variables, while environment secrets retain precedence.

The dataset dropdown includes nested JSON files and preserves a missing saved selection rather than silently substituting another file. Missing selections disable Run. Omitted datasets default to users.json, which must exist.

CSV, inline and environment datasets are not supported. Convert older rows to a JSON file and update the plan's dataset reference; no automatic conversion overwrites your files.

History And Reports

Local history keeps up to 100 request summaries per workspace folder: request name, method, environment, status, duration and timestamp. It does not persist bodies, credentials or resolved URLs and does not provide full replay snapshots.

Suite/load results include completed, failed, cancelled and unstarted row-iterations, HTTP attempts, requests per second, min/max/mean duration, p50/p95/p99 latency, error rate and non-2xx count.

• Retries are additional HTTP attempts.
• Expected negative responses can pass while still increasing the non-2xx count.
• A flow failure without an HTTP attempt does not increase the HTTP error rate.
• Percentiles use observed attempt durations, including transport and validation overhead.
• Throughput excludes definition loading; exported JSON is metadata-only, without response bodies, URLs, row values or secrets.

Import, Export And Compatibility

Nodexa uses its own schema-validated JSON definitions. It is not a Bruno/Postman file or script compatibility layer.

HTTP endpoints can accept manually supplied JSON or text bodies, but this does not imply dedicated protocol editors, discovery or authentication integrations.

File Layout

<workspace>/
  .nodexa/
    env/
      dev.json
      prod.json
  nodexa/
    collection/
      create-user.json
      users/
        lookup.json
    flows/
      users.json
    dataset/
      users.json
    suites/
      smoke.json
    load-tests/
      users-load.json

Commit shared requests, workflows, plans and non-secret datasets under nodexa/. Never commit .nodexa/ or embedded credentials. Requests reference collection-relative paths; plan entries and datasets are relative to their owning directories. Workspace-boundary checks reject escaping paths.

Safety And Limits

Writes and execution require workspace trust. Protected environments require confirmation; load tests require confirmation even in unprotected environments. Active runs block conflicting Nodexa runs and environment changes.

Response HTML is displayed as inert text. Secret redaction is best-effort, not a guarantee for transformed or unrelated secrets returned by servers. Repeated writes, retries and loads can create real side effects; prefer test environments and idempotency keys where appropriate.

There are no user settings for disabling TLS verification, automatically following redirects or choosing arbitrary transport limits in this release.

Requirements

• VS Code 1.95 or newer.
• A local folder/workspace containing request and test definitions.
• Workspace trust for writes and execution.
• Access to the API endpoints you configure.
• Node.js 22.15 or newer for development tooling, not as a separate runtime requirement for installing the VSIX.

Troubleshooting

Support

When reporting an issue through your team's repository or support channel, include:

• Nodexa and VS Code versions, OS and whether the workspace is multi-root.
• Steps to reproduce, expected behavior and the actual result.
• A minimal redacted request, flow or test-plan JSON example.
• Relevant error messages or logs with credentials and personal data removed.

Do not attach local environment secrets or unredacted API responses. No public Marketplace or issue-tracker URL is asserted here; use the distribution/support channel supplied with your build.

Development From Source

npm ci
npm run compile
npm test
npm run check:webview
npm run test:extension
npm run package

Press F5 to launch an Extension Development Host. Use npm run preview for the loopback-only browser harness; /flows previews the designer and /tests previews plans. Preview saves and configuration are in-memory substitutes, not real VS Code storage.

Build a local VSIX from the repository root:

npm exec --yes --package=node@22 --package=@vscode/vsce -- \
  vsce package --allow-missing-repository --skip-license \
  --changelog-path docs/CHANGELOG.md

This creates a versioned package and does not publish it. Marketplace publishing separately requires a publisher account you control. The source repository also contains an example Go API; follow docs/example-api.md and use npm run test:example after starting it.

Roadmap

Version 1.1.0 ships Retry, Timeout, Parallel, Join, Display, Transform and Try/Catch/Finally. Further data operators, scopes/subflows, compensation, breakpoints and additional protocols remain planned. Parallel follows the wait-all-then-fail policy today.

Visual assertion building, import/export integrations, OAuth flows, arbitrary scripting, AI assistance and a standalone CLI are not shipped features. The detailed guide and orchestration design document under docs/ distinguish current behavior from planned work.

Documentation

The root README is this overview and supplies the extension's installation/details page. Supporting Markdown lives under docs/ in the source repository. Packaging keeps the guides there, while VSCE places the changelog at its standard package path for the extension's Changes tab: