Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.markapidown.net/llms.txt

Use this file to discover all available pages before exploring further.

Every execution command in MarkApiDown — mad exec, mad flow, and mad request --verbose — accepts an --output flag that controls how results are printed. Choose the format that fits your context: console for interactive use, json when a script needs to parse results, junit for CI test reporters, and markdown when you want a shareable report. The format flag is identical across all three commands, so the examples below apply everywhere.

​
Overview

mad exec <file> --output=<format>
mad flow <pipeline> --output=<format>
mad request <METHOD> <URL> --verbose --output=<format>

console

Colored terminal output with status, timing, and request/response diff. The default for interactive use.

json

Structured JSON object. Parse it in scripts, dashboards, or custom reporters.

junit

JUnit XML. Drop into GitHub Actions, Jenkins, CircleCI, or any CI system with a test-results reporter.

markdown

A markdown report. Save it to a file, post it as a PR comment, or include it in documentation.

​
console (default)

The console format is designed for human readers. It prints a color-coded summary showing the HTTP status, response time, and a diff between the expected and actual response. Passing assertions are marked with ✓; failing ones with ✗ and an inline diff. 
mad exec api-docs/apis/users/get-user.md
You do not need to pass --output=console explicitly — it is the default for all execution commands. 
# Equivalent — both use console output
mad exec api-docs/apis/users/get-user.md
mad exec api-docs/apis/users/get-user.md --output=console
Disable color output (for example in log files or dumb terminals) by passing the global --no-color flag or setting the NO_COLOR environment variable: 
mad exec api-docs/apis/users/get-user.md --no-color
NO_COLOR=1 mad exec api-docs/apis/users/get-user.md

​
json

The json format emits a single JSON object to stdout. Use it whenever another program needs to consume the result — a custom Slack notifier, a dashboard ingest script, or a PR comment bot. 
mad exec api-docs/apis/users/get-user.md --output=json
Sample output 
{
  "passed": true,
  "status": 200,
  "duration_ms": 143,
  "endpoint": "api-docs/apis/users/get-user.md",
  "env": "dev",
  "response": {
    "status": 200,
    "headers": {
      "content-type": "application/json",
      "x-request-id": "d3f1a29c"
    },
    "body": "{\"id\": 1, \"name\": \"Ada Lovelace\"}"
  },
  "assertions": [
    {
      "description": "status is 200",
      "passed": true
    },
    {
      "description": "response.body.id equals postId",
      "passed": true
    }
  ]
}
Key fields
FieldTypeDescription
passedbooleantrue if all assertions passed, false otherwise.
statusintegerHTTP status code of the actual response.
duration_msintegerTime from request dispatch to response receipt in milliseconds.
endpointstringPath of the spec file that was executed.
envstringEnvironment name used for variable resolution.
response.statusintegerRaw HTTP status code.
response.headersobjectResponse headers as key/value pairs.
response.bodystringRaw response body.
assertionsarrayPer-assertion results with description and passed.
Scripting example Parse the output with jq to extract just the pass/fail status and duration: 
result=$(mad exec api-docs/apis/orders/create-order.md --output=json)
passed=$(echo "$result" | jq -r '.passed')
duration=$(echo "$result" | jq -r '.duration_ms')
echo "Passed: $passed | Duration: ${duration}ms"

​
junit

The junit format produces JUnit-compatible XML. Every major CI system — GitHub Actions, Jenkins, CircleCI, GitLab CI, Buildkite — can parse JUnit XML to display per-test pass/fail annotations, track trends, and surface failures inline on pull requests. 
mad exec api-docs/apis/users/get-user.md --output=junit > results.xml
mad flow api-docs/flows/smoke-test.md --output=junit > flow-results.xml

​
GitHub Actions upload example

Save the JUnit XML as an artifact and use a test-reporter action to annotate the pull request: 
- name: Run API specs
  run: mad flow api-docs/flows/smoke-test.md --env=staging --output=junit > test-results.xml
  env:
    MAD_BASE_URL: ${{ secrets.STAGING_BASE_URL }}
    MAD_AUTH_TOKEN: ${{ secrets.STAGING_TOKEN }}

- name: Upload test results
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: api-test-results
    path: test-results.xml
Use if: always() on the upload step so the XML file is saved even when the spec run fails. Without it, the artifact is silently discarded when any test does not pass.

​
Jenkins pipeline example

stage('API Tests') {
  steps {
    sh 'mad flow api-docs/flows/smoke-test.md --output=junit > results.xml'
  }
  post {
    always {
      junit 'results.xml'
    }
  }
}
Combine --output=junit with mad flow to get a single XML file covering every step in your pipeline. This gives CI a consolidated test report rather than one file per endpoint, and it lets you track test trends across pipeline runs over time.

​
markdown

The markdown format generates a human-readable markdown report. Use it to save a record of a test run to disk, embed it in documentation, or post it as a pull request comment via a CI step. 
mad exec api-docs/apis/users/get-user.md --output=markdown
mad flow api-docs/flows/smoke-test.md --output=markdown > reports/smoke-$(date +%Y%m%d).md

​
Save to a file

mad flow api-docs/flows/regression.md \
  --env=staging \
  --output=markdown \
  > reports/regression-$(date +%F).md

​
Post as a GitHub PR comment

Combine with the gh CLI to post the report as a pull request comment automatically: 
- name: Run regression tests
  run: |
    mad flow api-docs/flows/regression.md \
      --env=staging \
      --output=markdown \
      > report.md

- name: Comment on PR
  if: github.event_name == 'pull_request'
  run: gh pr comment ${{ github.event.pull_request.number }} --body-file report.md
  env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

​
Choosing the right format

ScenarioRecommended format
Developing locally, checking a single endpointconsole
Script that branches on pass/fail and reads response fieldsjson
CI job that needs test-result annotations on a PRjunit
Saving a record of a release smoke testmarkdown
Posting a test summary as a PR commentmarkdown
Parsing failure reason programmatically in CIjson