feat: add --expect to assert JMESPath expressions on the response

[jongio]

What

Adds a repeatable --expect flag that evaluates a JMESPath expression against the JSON response and exits non-zero when it does not hold.

• --expect "<jmespath>" passes when the result is truthy under JMESPath rules (false, null, empty string, empty array, and empty object are falsy; every other value, including any number, is truthy).
• --expect "<jmespath>=<value>" passes when the result equals value. Scalars compare by their plain string form, so properties.provisioningState=Succeeded, count=3, and active=true all work. A missing field resolves to null, so field=null is a valid assertion.
• Repeatable: pass --expect several times to check more than one thing. The first failing assertion is reported.

Why

There is no built-in way to assert something about a response body in a script or CI step. Today you pipe --query into test or jq. --expect folds that into one call: run the request, print the body, and fail the step when the response is not what you expected.

Behavior

• The response body still prints (unless suppressed), then the assertion runs. This mirrors how --fail prints the body before returning its exit code.
• Assertions run against the original response body, so --expect stays independent of what --query narrows for display.
• Exit codes: an assertion that does not hold exits 1; a non-JSON response, an empty expression, or an invalid JMESPath expression exits 2.
• The expr=value split only triggers on a standalone =, so JMESPath comparators (==, !=, <=, >=) inside a bare boolean expression are preserved.

Example

# Fail a CI step unless the resource group is provisioned
azd rest get https://management.azure.com/subscriptions/{sub}/resourceGroups/{rg}?api-version=2021-04-01 \
  --expect "properties.provisioningState=Succeeded"

Tests

• Unit tests cover the argument split (truthy vs equality, comparator preservation), the JMESPath truthiness rules, equality against strings, numbers, booleans, and null, multiple assertions stopping at the first failure, and the usage-error paths (non-JSON, invalid expression, empty expression) returning exit 2.
• Execute-level tests confirm a passing assertion prints the body, a failing assertion returns exit 1 while still printing the body, and --expect works alongside --query.

Docs updated in the README, the reference flag table, and the exit-code table.

Closes #269

[github-actions]

🚀 Website Preview

Your PR preview is ready!

📎 Preview URL: https://jongio.github.io/azd-rest/pr/272/

This preview will be automatically cleaned up when the PR is closed.

[github-actions]

🚀 Test This PR

A preview build (0.5.0-pr272) is ready for testing!

One-Line Install (Recommended)

PowerShell (Windows):

iex "& { $(irm https://raw.githubusercontent.com/jongio/azd-rest/main/scripts/install-pr.ps1) } -PrNumber 272 -Version 0.5.0-pr272"

Bash (macOS/Linux):

curl -fsSL https://raw.githubusercontent.com/jongio/azd-rest/main/scripts/install-pr.sh | bash -s 272 0.5.0-pr272

Uninstall

PowerShell (Windows):

iex "& { $(irm https://raw.githubusercontent.com/jongio/azd-rest/main/scripts/uninstall-pr.ps1) } -PrNumber 272"

Bash (macOS/Linux):

curl -fsSL https://raw.githubusercontent.com/jongio/azd-rest/main/scripts/uninstall-pr.sh | bash -s 272

---

Build Info:

• Version: 0.5.0-pr272
• Commit: 1783179
• Release: View pre-release