diff --git a/docs/decisions/README.md b/docs/decisions/README.md index 211fc5b..ccc7fab 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -1,3 +1,6 @@ +--- +description: "Index of Sendra design decisions: unasserted statuses under test, how exit codes are split, script sandboxing and the precedence chain." +--- # Design decisions The rationale behind the design choices in Sendra's schema and CLI that could diff --git a/docs/decisions/exit-codes.md b/docs/decisions/exit-codes.md index 17a698b..036dd6d 100644 --- a/docs/decisions/exit-codes.md +++ b/docs/decisions/exit-codes.md @@ -1,3 +1,6 @@ +--- +description: "Why exit code 4 is separate from 3, why an unsendable request under test exits 1, and how the codes rank across a whole collection." +--- # Exit codes: why the numbers are split the way they are Background: the full table of codes and what each one means is in diff --git a/docs/decisions/precedence-chain.md b/docs/decisions/precedence-chain.md index 2414507..2be1877 100644 --- a/docs/decisions/precedence-chain.md +++ b/docs/decisions/precedence-chain.md @@ -1,3 +1,6 @@ +--- +description: "The full precedence chain for a request value: defaults, config, environment files, captures, CLI overrides, then pre_request scripts." +--- # Precedence, start to finish Every layer that can decide a value for a request is introduced in its own diff --git a/docs/decisions/sandboxing.md b/docs/decisions/sandboxing.md index 7787efa..b2a1e63 100644 --- a/docs/decisions/sandboxing.md +++ b/docs/decisions/sandboxing.md @@ -1,3 +1,6 @@ +--- +description: "How pre_request and post_request scripts are kept away from the filesystem and network: nothing registered, no import, no eval, an operation cap." +--- # Sandboxing Background: what a `pre_request`/`post_request` script can see and do is in diff --git a/docs/decisions/why-test-ignores-unasserted-status.md b/docs/decisions/why-test-ignores-unasserted-status.md index b8b378b..301c583 100644 --- a/docs/decisions/why-test-ignores-unasserted-status.md +++ b/docs/decisions/why-test-ignores-unasserted-status.md @@ -1,3 +1,6 @@ +--- +description: "Why sendra test does not fail a run on an unasserted 404, and why a post_request script counts as a check the same way an assertion does." +--- # Why `test` ignores an unasserted status Background: the mechanics and the four outcome categories (`passed`, `failed`, diff --git a/docs/reference.md b/docs/reference.md index 444e868..64e111e 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -1,3 +1,6 @@ +--- +description: "Index of the Sendra reference: request files, assertions, environments, scripting, exit codes, JSON output and the TUI, with a link to each page." +--- # Reference The full schema and behavior reference for Sendra, split by topic. Start at diff --git a/docs/reference/assertions.md b/docs/reference/assertions.md index ba00da9..3a4c791 100644 --- a/docs/reference/assertions.md +++ b/docs/reference/assertions.md @@ -1,3 +1,6 @@ +--- +description: "Check status, headers, body text and JSON paths with assertions in a request file, plus status_in, regex, timing, negation and comparisons." +--- # Assertions A request can say what it expects of the response, under an optional diff --git a/docs/reference/capturing.md b/docs/reference/capturing.md index 7483820..3096930 100644 --- a/docs/reference/capturing.md +++ b/docs/reference/capturing.md @@ -1,3 +1,6 @@ +--- +description: "Capture values from a JSON body, header or status with a capture block, then reuse them as variables in later requests to chain calls." +--- # Capturing values and chaining requests A request can pull values out of its response and hand them to the requests diff --git a/docs/reference/cli-overrides.md b/docs/reference/cli-overrides.md index dee518e..da9dfb4 100644 --- a/docs/reference/cli-overrides.md +++ b/docs/reference/cli-overrides.md @@ -1,3 +1,6 @@ +--- +description: "Flags for sendra run and test that override files for one invocation: -H, --var, --timeout, --insecure, --proxy, client certificates, --cookie-jar." +--- # CLI overrides Flags that change one invocation without touching a file, on `sendra run` and diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index 4bf76d3..374b471 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -1,3 +1,6 @@ +--- +description: "Set project or global defaults in config.yaml: headers, timeout, redirects, TLS verification, proxy, client certificates and a cookie jar." +--- # Configuration Defaults that apply to every request live in a config file. There are two, both diff --git a/docs/reference/development.md b/docs/reference/development.md index 5276da7..dc7d6ad 100644 --- a/docs/reference/development.md +++ b/docs/reference/development.md @@ -1,3 +1,6 @@ +--- +description: "Build, test, format and lint the Sendra Rust workspace with the five cargo commands CI runs, and why the test suite never touches the network." +--- # Development ```sh diff --git a/docs/reference/environments.md b/docs/reference/environments.md index 19618a8..5e1eefe 100644 --- a/docs/reference/environments.md +++ b/docs/reference/environments.md @@ -1,3 +1,6 @@ +--- +description: "Define environment files of variables, use them as {{name}} in requests, keep secrets in OS variables with ${VAR}, and set a default auth." +--- # Environments and variables An environment is a flat file of variables at diff --git a/docs/reference/exit-codes.md b/docs/reference/exit-codes.md index e096f0e..5ab12a3 100644 --- a/docs/reference/exit-codes.md +++ b/docs/reference/exit-codes.md @@ -1,3 +1,6 @@ +--- +description: "The exit code table for the sendra binary: what 0, 1, 2, 3 and 4 mean under run and test, for shell scripts and CI pipelines." +--- # Exit codes One table for the whole binary, not one per subcommand: `run` and `test` answer diff --git a/docs/reference/json-output.md b/docs/reference/json-output.md index e860bb3..27f0f75 100644 --- a/docs/reference/json-output.md +++ b/docs/reference/json-output.md @@ -1,3 +1,6 @@ +--- +description: "The --json output of sendra run and test: one JSON object per run with responses, assertion results, captures and a test summary." +--- # JSON output `--json` replaces the terminal output with one JSON object describing the whole diff --git a/docs/reference/json-schema.md b/docs/reference/json-schema.md index dd704a5..2106513 100644 --- a/docs/reference/json-schema.md +++ b/docs/reference/json-schema.md @@ -1,3 +1,6 @@ +--- +description: "Get JSON Schema files for Sendra requests, collections, config and environments, and set up VS Code for autocomplete and validation." +--- # JSON Schema / editor support `schema/*.schema.json` are [JSON Schema](https://json-schema.org/) documents diff --git a/docs/reference/requests.md b/docs/reference/requests.md index f38845b..7d2f73a 100644 --- a/docs/reference/requests.md +++ b/docs/reference/requests.md @@ -1,3 +1,6 @@ +--- +description: "The Sendra request and collection YAML format: fields, repeated headers, and authentication with bearer, basic, API key and OAuth." +--- # Request and collection file shape ## Request file shape diff --git a/docs/reference/running-and-testing.md b/docs/reference/running-and-testing.md index 171e2b1..09c2bc3 100644 --- a/docs/reference/running-and-testing.md +++ b/docs/reference/running-and-testing.md @@ -1,3 +1,6 @@ +--- +description: "Send requests and collections with sendra run, or check them with sendra test, including output format, result categories and the summary." +--- # Running and testing requests ## Running requests diff --git a/docs/reference/scripting.md b/docs/reference/scripting.md index b84e15b..d8bc17c 100644 --- a/docs/reference/scripting.md +++ b/docs/reference/scripting.md @@ -1,3 +1,6 @@ +--- +description: "Write pre_request and post_request scripts in Rhai to change a request or check a response, with what each can see and the run order." +--- # Scripting A request can carry two inline scripts: `pre_request`, which runs just before it diff --git a/docs/reference/tui.md b/docs/reference/tui.md index 73b1f92..0fd1cc3 100644 --- a/docs/reference/tui.md +++ b/docs/reference/tui.md @@ -1,3 +1,6 @@ +--- +description: "Use the sendra tui terminal app (TUI) to browse, run and edit requests, switch environments, review run history and find every keybinding." +--- # The interactive TUI `sendra tui` opens a full-screen terminal app for browsing and running the