Skip to content

Commit 2f93a45

Browse files
adamaltmanadamaltman
committed
docs: add respect command docs
1 parent 84a6252 commit 2f93a45

File tree

3 files changed

+199
-4
lines changed

3 files changed

+199
-4
lines changed

‎docs/commands/generate-arazzo.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# `generate-arazzo`
2+
3+
Auto-generate an Arazzo file based on an OpenAPI description file.
4+
5+
If `examples` are provided in the OpenAPI description, they are used as input data for test requests.
6+
If `schema` is provided, the config generates fake data based on the description schema.
7+
By default, data for requests comes from the description at run-time.
8+
To materialize tests with the data, use the `--extended` option.
9+
10+
The `--extended` option also demonstrates how `respect` gets data from an OpenAPI description.
11+
12+
13+
{% admonition type="warning" %}
14+
15+
Given the nature of OpenAPI, the generated Arazzo file is not a complete test file and may not function. Dependencies between endpoints are not resolved.
16+
17+
It acts as a starting point for a test file and needs to be extended to be functional.
18+
{% /admonition %}
19+
20+
## Usage
21+
22+
```sh
23+
npx @redocly/cli generate-arazzo <your-OAS-description-file> [-o | --output-file] [--extended]
24+
```
25+
26+
## Options
27+
28+
{% table %}
29+
* Option {% width="20%" %}
30+
* Type {% width="15%" %}
31+
* Description
32+
---
33+
* -o, --output-file
34+
* string
35+
* Path to the OAS description file. If the file name is not provided, the default name is used - `auto-generate.yaml`. Example: `npx @redocly/cli generate-arazzo OAS-file.yaml -o=example.yaml`
36+
---
37+
* --extended
38+
* boolean
39+
* By default, data for requests comes from the description at runtime. This option generates a test config file with data populated from the description. Example: `npx @redocly/cli generate-arazzo OAS-file.yaml -o=example.yaml --extended`.
40+
---
41+
* --with-expectations
42+
* boolean
43+
* By default, data for requests comes from the description at runtime. This option generates a test config file with data populated from the description with additional expectations. Example: `npx @redocly/cli generate-arazzo OAS-file.yaml -o=example.yaml --with-expectations`.
44+
{% /table %}
45+
46+
<!-- TODO
47+
## Examples
48+
49+
## Resources -->

‎docs/commands/index.md‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,11 @@ tocMaxDepth: 2
66

77
Documentation commands:
88

9-
- [`preview-docs`](preview-docs.md) Preview API reference docs for the specified API description.
10-
- [`build-docs`](build-docs.md) Build API description into an HTML file.
119
- [`preview`](preview.md) Start a local preview of a Redocly project with one of the product NPM packages.
1210
- [`translate`](translate.md) Generate translation keys for a Redocly Realm, Reef, or Revel project.
1311
- [`eject`](eject.md) Eject and modify components from the core theme in a Redocly Realm, Reef, or Revel project.
12+
- [`preview-docs`](preview-docs.md) Preview API reference docs for the specified API description. Will be deprecated in the future.
13+
- [`build-docs`](build-docs.md) Build API description into an HTML file. Will be deprecated in the future.
1414

1515
API management commands:
1616

@@ -24,6 +24,11 @@ Linting commands:
2424
- [`lint`](lint.md) Lint API description.
2525
- [`check-config`](check-config.md) Lint Redocly configuration file.
2626

27+
Testing commands:
28+
29+
- [`respect`](respect.md) Execute API tests described in an Arazzo file.
30+
- [`generate-arazzo`](generate-arazzo.md) Generate an Arazzo file from an OpenAPI description.
31+
2732
Redocly platform commands:
2833

2934
- [`login`](login.md) Login to the Redocly API registry with an access token or to the Reunite API.
@@ -44,7 +49,7 @@ There are some parameters supported by all commands:
4449
`--help` display the command help, or the help for the subcommand if you used one. For example:
4550

4651
```bash
47-
redocly lint --help
52+
npx @redocly/cli lint --help
4853
```
4954

5055
Try these with any of the other commands.
@@ -60,7 +65,7 @@ If Redocly CLI finds `redocly.yaml` in the root directory, it uses the options s
6065
You can also specify a config file to most commands using `--config myconfig.yaml` as part of the command. For example:
6166

6267
```bash
63-
redocly lint --config redocly-official.yaml openapi.yaml
68+
npx @redocly/cli lint --config redocly-official.yaml openapi.yaml
6469
```
6570

6671
For more information, refer to the [Redocly configuration file](../configuration/index.md) docs.

‎docs/commands/respect.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
# `respect`
2+
3+
Use this command to execute API tests described in an Arazzo file.
4+
In addition to the Arazzo specification, `respect` supports specification extensions for API testing: `x-operation` and `x-serverUrl`.
5+
6+
## Usage
7+
8+
```sh
9+
npx @redocly/cli respect <your-test-file | multiple files | files bash query> [-w | --workflow] [-s | --skip] [-v | --verbose] [-i | --input]
10+
```
11+
12+
## Options
13+
14+
{% table %}
15+
* Option {% width="20%" %}
16+
* Type {% width="15%" %}
17+
* Description
18+
---
19+
* -w, --workflow
20+
* [string]
21+
* Workflow names from the test file to run.
22+
For example, the following command runs "first-flow" and "second-flow" workflows from the "test-file.yaml" test file: `npx @redocly/cli respect test-file.yaml --workflow first-flow second-flow`
23+
{% admonition type="warning" %}
24+
The `--workflow` option can't be used with `--skip`.
25+
{% /admonition %}
26+
---
27+
* -s, --skip
28+
* [string]
29+
* Workflow names from the test file to skip.
30+
For example, the following command skips the "first-flow" workflow from the "test-file.yaml" test file: `npx @redocly/cli respect test-file.yaml --skip first-flow`
31+
{% admonition type="warning" %}
32+
Warning: the `--skip` option can't be used with `--workflow`.
33+
{% /admonition %}
34+
---
35+
* -v, --verbose
36+
* boolean
37+
* Runs the command in verbose mode to help with troubleshooting issues.
38+
For example, the following command runs all workflows from the "test-file.yaml" test file in verbose mode: `npx @redocly/cli respect test-file.yaml --verbose`
39+
---
40+
* --har-output
41+
* string
42+
* Path for the `har` file for saving logs.
43+
For example, the following command runs all workflows from the "test-file.yaml" test file and saves the logs to the "logs.har" file: `npx @redocly/cli respect test-file.yaml --har-output='logs.har'`
44+
---
45+
* --json-output
46+
* string
47+
* Path for the 'json` file for saving logs.
48+
For example, the following command runs all workflows from the "test-file.yaml" test file and saves the logs to the "logs.json" file: `npx @redocly/cli respect test-file.yaml --json-output='logs.json'`
49+
---
50+
* --input
51+
* string
52+
* Input parameters with values that are mapped to the workflow inputs description.
53+
For example, the following command maps the "userEmail" and "userPassword" inputs and values to all workflows in the "test.yaml" test file: `npx @redocly/cli respect test.yaml --input [email protected] --input userPassword=12345`.
54+
You can also use an environment variable to set the input, as in the following example: `REDOCLY_CLI_RESPECT_INPUT='[email protected],userPassword=12345' npm run cli respect test.yaml`
55+
56+
You can even include nested values, as in the following example command that maps the "nestedKey" input and value to all workflows in the "test-file.yaml" test file: `npx @redocly/cli respect test-file.yaml --input '{"key": "value", "nested": {"nestedKey": "nestedValue"}}'`.
57+
You can also use an environment variable to set the input, as in the following example: `REDOCLY_CLI_RESPECT_INPUT='{"key":"value","nested":{"nestedKey":"nestedValue"}}' npx @redocly/cli respect test-file.yaml`
58+
---
59+
* --server
60+
* string
61+
* Server overrides for the `sourceDescriptions` object.
62+
For example, the following command runs all workflows from the "test-file.yaml" test file and instead of using the server listed in the API description, uses the server at "https://test.com": `npx @redocly/cli respect test-file.yaml --server test=https://test.com`
63+
64+
You can also pass the server overrides as an environment variable, as in the following example:
65+
`REDOCLY_CLI_RESPECT_SERVER="test=https://test.com"`
66+
---
67+
* --residency
68+
* string
69+
* Residency location of Reunite application to use if `login` command was not run before.
70+
Default: `us`.
71+
You can also pass the residency as an environment variable, as in the following example:
72+
`REDOCLY_CLI_RESPECT_RESIDENCY='eu'`
73+
{% /table %}
74+
75+
## Examples
76+
77+
- Run the tests by running the following command: `npx @redocly/cli respect <your-test-file>`.
78+
- Run multiple tests by running the following command: `npx @redocly/cli respect <your-test-file-one> <your-test-file-two>`.
79+
- Run multiple tests by running the following command with bash selector : `npx @redocly/cli respect $(find ./path-to-tests-folder -type f -name '*.arazzo.yaml')`.
80+
81+
**Example output**
82+
83+
```bash
84+
Running workflow warp.arazzo.yaml / missionLostInvention
85+
86+
✓ POST /anchors - step setAnchorToCurrentTime
87+
    ✓ status code check (Response code 201 matches one of description codes: [201, 409])
88+
    ✓ content-type check
89+
    ✓ schema check
90+
91+
✓ POST /timelines - step createTimelineTo1889
92+
    ✓ status code check (Response code 201 matches one of description codes: [201])
93+
    ✓ content-type check
94+
    ✓ schema check
95+
96+
✓ POST /travels - step travelTo1889
97+
    ✓ status code check (Response code 200 matches one of description codes: [200, 400])
98+
    ✓ content-type check
99+
    ✓ schema check
100+
101+
✓ POST /items - step findAndRegisterBlueprint
102+
    ✓ status code check (Response code 200 matches one of description codes: [200, 409])
103+
    ✓ content-type check
104+
    ✓ schema check
105+
106+
✓ POST /paradox-checks - step avoidParadox
107+
    ✓ success criteria check
108+
    ✓ success criteria check
109+
    ✓ status code check (Response code 200 matches one of description codes: [200, 400])
110+
    ✓ content-type check
111+
    ✓ schema check
112+
113+
✓ POST /travels - step returnToPresent
114+
    ✓ status code check (Response code 200 matches one of description codes: [200, 400])
115+
    ✓ content-type check
116+
    ✓ schema check
117+
118+
119+
  Summary for warp.arazzo.yaml
120+
  
121+
  Workflows: 1 passed, 1 total
122+
  Steps: 6 passed, 6 total
123+
  Checks: 20 passed, 20 total
124+
  Time: 1060ms
125+
126+
127+
┌──────────────────────────────────────────────────────────┬────────────┬─────────┬─────────┬──────────┬─────────┐
128+
│ Filename │ Workflows │ Passed │ Failed │ Warnings │ Skipped │
129+
├──────────────────────────────────────────────────────────┼────────────┼─────────┼─────────┼──────────┼─────────┤
130+
│ ✓ warp.arazzo.yaml │ 1 │ 1 │ - │ - │ - │
131+
└──────────────────────────────────────────────────────────┴────────────┴─────────┴─────────┴──────────┴─────────┘
132+
```
133+
134+
<!-- UNCOMMENT AFTER OTHER CONTENT PUBLISHES AND CHECK RELATIVE LINKS
135+
## Resources
136+
137+
- Learn more about using mTLS with Respect in [Use mTLS](../../respect/guides/mtls-cli.md).
138+
- Follow steps to test API sequences in [Test a sequence of API calls](../../respect/guides/test-api-sequences.md).
139+
- Learn what Respect is and how you can use it to test API in the [Respect](../../respect/index.md) concept document.
140+
- Link to learning center for Arazzo too
141+
-->

0 commit comments

Comments
 (0)