CLI Tools for Connectors

Analyze API requests, generate schemas, and create automated tests with the Rover CLI
Requires ≥ Rover 0.36.0, Federation 2.12.1

Available tools

rover connector test

Learn more about testing Connectors.

CLI options
log
1Usage: rover connector test [OPTIONS]
2
3Options:
4  -f, --file <FILE>
5          Defines a single test suite file source If no directory is passed. It will execute all test cases in that file. If this flag is not present it will default to `--directory tests/` and self discover any files in `./tests/**/*.connector.yaml`
6
7  -q, --quiet
8          Hides test progression. Defaults to 'false'
9
10  -d, --directory <DIRECTORY>
11          Defines a test suite directory, will look for any file ending in `.connector.yml`. If no directory and no file is passed, it will default to `--directory tests/` and self discover any files in `./tests/**/*.connector.yaml`
12
13  -v, --verbose
14          Enable verbose logging. Defaults to 'false'
15
16          NOTE: Overrides the --log-level flag
17
18  -l, --log-level <LEVEL>
19          Sets the log-level of the CLI. Defaults to 'INFO'
20
21      --no-fail-fast
22          Avoids failure on asserting error. Failures and errors encountered will be reported at the end of the execution. Recommended flag for CI environments
23
24      --schema <SCHEMA_PATH>
25          Schema file to override `config.schema` (or missing fields) for all test suites executed
26
27  -o, --output <OUTPUT>
28          JUnit XML Report output location
29
30  -h, --help
31          Print help (see a summary with '-h')

rover connector list

This command lists all Connectors in a GraphQL schema file. If supergraph.yml contains only one subgraph, the schema is automatically detected. Otherwise, use the --schema flag to specify the GraphQL schema file to list all Connectors from.

rover connector run

This command executes a Connector against a live service.

To run a Connector, specify the following parameters:

  • --path: the path to the GraphQL schema file

  • --connector-id: the specific Connector to run within that schema. See Connector IDs for more information.

  • --variables: any Connector variables, expressed as a JSON object, to use when calling the Connector. For a list of available variables, see the Variable reference documentation.

Example: rover connector run
shell
1rover connector run \
2--path build/connectors/output.graphql \
3--connector-id Query.users_by_id \
4--variables '{"$args": {"users": "1"}}'
This returns a response like the following:
JSON
1{
2  "request": {
3    "method": "GET",
4    "uri": "http://localhost:5050/users/1",
5    "headers": {},
6    "problems": []
7  },
8  "response": {
9    "body": {
10      "greeting": "hi",
11      "id": "1",
12      "theme": "purple",
13      "username": "Bob"
14    },
15    "status": 200,
16    "headers": {
17      "server": "Werkzeug/3.1.3 Python/3.9.6",
18      "date": "Fri, 12 Sep 2025 14:23:10 GMT",
19      "content-type": "application/json",
20      "content-length": "61",
21      "connection": "close"
22    },
23    "problems": [],
24    "mapped_data": {
25      "greetingSize": 2,
26      "id": "1",
27      "theme": "purple",
28      "username": "Bob"
29    }
30  }
31}
32
note
Rover outputs a pretty-printed version of the preceding JSON output, but all of the data is the same.

Connector IDs

A Connector can optionally specify an ID in the @connect directive:

GraphQL
1@connect(id: "MyNiceId", ...)

If a custom id isn't specified in the @connect directive, use the Connector's coordinates.

Coordinates follow the pattern ParentType.field. If you have more than one Connector on a type or field, you can use the [index] suffix to differentiate Connectors. For example, Product.reviews, without an index, refers to the first Connector on the Product.reviews field, and Product.reviews[2] refers to the third Connector on the same field.

rover connector analyze

Experimental Feature
note
This tool only supports macOS.This tool depends on libssl which is not configured by default on non-macOS platforms.

This command captures snapshots of requests and responses for one or more APIs. You can use these analysis snapshots to define tests with the testing framework or to generate a GraphQL schema.

This command includes the interactive, curl, and clean commands.

interactive command

This command analyzes calls made from your terminal. This includes running a curl command against an endpoint, running Python or Java code, or running any shell command.

Usage
When you run rover connector analyze interactive, the command starts an interactive shell. Run curl commands within that interactive shell to collect analysis snapshots.When you're done collecting data, type exit to exit the process.
note
Interactive analysis ignores calls from clients that don't honor the HTTP_PROXY or GLOBAL_PROXY environment variables.

curl command

This command captures data from a single request/response using the curl command. The curl command mimics the curl utility flags and inputs, so you can copy and paste an existing curl command into the command line.

This command generates an analysis directory with snapshots for the request and response.

CLI options
log
1rover connector analyze curl [OPTIONS] <URL>
2
3Arguments:
4  <URL>
5          Sets the endpoint to call
6
7Options:
8  -H, --headers <HEADERS>...
9          Headers to include in request
10
11  -q, --quiet
12          Hides test progression. Defaults to 'false'
13
14  -v, --verbose
15          Enable verbose logging. Defaults to 'false'.
16
17          NOTE: Overrides the --log-level flag
18
19  -X, --method <REQUEST>
20          Request method to use for call
21
22  -l, --log-level <LEVEL>
23          Sets the log-level of the CLI. Defaults to 'Warn'
24
25  -t, --timeout <CONNECT_TIMEOUT>
26          Connection timeout in seconds
27
28  -d, --data <DATA>
29          Add JSON data to the request
30
31  -a, --analysis-dir <ANALYSIS_DIR>
32          Set analysis directory to save data to
33
34  -h, --help
35          Print help (see a summary with '-h')
Example: rover connector analyze curl
sh
1$ rover connector analyze curl -X GET 'https://httpbin.org/json?name=Your-Name' -H 'accept: application/json' -H 'x-user: 123'
The command generates the following files:

analysis/<id>_request.http

http
1GET https://httpbin.org/json?name=Julia
2accept: application/json
3x-user: 123

analysis/<id>_response.json

JSON
1{
2  "status": 200,
3  "headers": [
4    [
5      "x-user-id",
6      "ca42b19d-9068-4818-bb19-174fcf6e2e2f"
7    ]
8  ]
9}
note
Only non-standard headers (x-<HEADER_NAME>) are stored in the response file.

analysis/<id>_body.json

JSON
1{
2  "slideshow": {
3    "author": "Yours Truly", 
4    "date": "date of publication", 
5    "slides": [
6      {
7        "title": "Wake up to WonderWidgets!", 
8        "type": "all"
9      }, 
10      {
11        "items": [
12          "Why <em>WonderWidgets</em> are great", 
13          "Who <em>buys</em> WonderWidgets"
14        ], 
15        "title": "Overview", 
16        "type": "all"
17      }
18    ], 
19    "title": "Sample Slide Show"
20  }
21}

clean command

This command removes the analysis/ directory and its contents.

rover connector generate

Experimental Feature
note
This tool only supports macOS.This tool depends on libssl which is not configured by default on non-macOS platforms.

This command generates a GraphQL schema from analysis data.

caution
You need existing analysis data to run this command.

By default, this command loads data from ./analysis and generates a schema at ./build/connectors/output.graphql.

You can customize the output directory, filenames, and where to load analysis snapshots using CLI options.

CLI options
log
1Usage: rover connector generate [OPTIONS]
2Options:
3  -n, --name <NAME>
4           Sets the name of the generated file (the generated file will be named `<name>.graphql`).
5          
6          Defaults to `output`
7  -q, --quiet
8          Hides test progression. Defaults to 'false'
9  -a, --analysis-dir <ANALYSIS_DIR>
10          Set analysis directory to load data from.
11          
12          Defaults to `./analysis/`
13  -v, --verbose
14          Enable verbose logging. Defaults to 'false'.
15          
16          NOTE: Overrides log-level
17  -l, --log-level <LEVEL>
18          Sets the log-level of the CLI. Defaults to 'Warn'
19          
20  -o, --output-dir <OUTPUT_DIR>
21          Set a custom directory to generate output files to.
22          
23          Defaults to `build/connectors/`.
24  -h, --help
25          Print help (see a summary with '-h')
Usage
  • Queries come from GET requests without a body and with only ID path arguments and/or query parameters.
  • Mutations come from other HTTP methods, such as POST and PUT.
note
The generated schema might need manual adjustments depending on your API patterns or desired field structure. Use the run command to test and refine the generated schemas.
Feedback

Edit in VSCode

Ask Community