Test Connectors

Use this guide when you want to exercise a Connector end-to-end from your terminal — inspect the outgoing request, confirm the tenant returns the response shape you expect, and iterate on request parameters without wiring the Connector into a widget first.

Prerequisites

• An active session — see Authenticate
• Either a Connector defined in connectors_registry.json, or a Connector already deployed to your tenant

Run a Connector

gsds connector test revenue-feed

Every run reports where the Connector was resolved from, in two steps:

• connectors_registry.json in your project — the root file the platform ingests
• the Connector persisted on the tenant your session is paired with

Resolution is local-first. If a name matches a Connector in connectors_registry.json, gsds uses that even when the tenant has a Connector by the same name — this lets you iterate locally without publishing.

The source: line prints before the request goes out, so on the tenant step it reports a plan rather than a result: source: no local definition - trying a connector persisted on your tenant. The settled value — source: local or source: remote — is what captures and --json output record.

When neither step holds the name, the failure reads Connector "x" is not defined in this project, and your tenant has no persisted connector under that name.

Provide a request body

Pass a JSON body from a file. --payload accepts file references only, prefixed with @, and the file must contain valid JSON.

gsds connector test revenue-feed --payload @body.json

Inline JSON is rejected — put the payload in a file and reference it.

Set query and path parameters

gsds connector test revenue-feed --query limit=5 --query cursor=abc
gsds connector test users --path-param user_id=42

Repeat --query and --path-param for each parameter.

See the rendered upstream request

Add --verbose to print the request gsds sends upstream, after Payload Templates have been rendered and headers applied. Use this when a Connector "looks right" locally but returns an unexpected response.

gsds connector test revenue-feed --verbose

Where runs are captured

Every run is written under .gsds/ in your project root, with sensitive request headers redacted. gsds init gitignores .gsds/ for you.

Use the capture directory to compare runs across changes, share reproduction cases without leaking credentials, and diff request shape after editing a Connector.

Limitations

• Composite Connectors cannot be tested. gsds connector test runs a single Connector; composite orchestration happens at request time inside a widget. To validate a composite, test each leaf Connector individually.

Next steps

• Drive gsds connector test --json from CI or an AI agent in Automate with CI and AI
• Look up every flag in the Command reference
• Review the Connector data model in Connectors