mmt-mcp 1.42.2-pre

package/dist/examples/intermediate/01_api_inputs_outputs/README.md

@@ -0,0 +1,46 @@
+# API Inputs & Outputs
+
+This example shows how to use **inputs** and **outputs** in `.mmt` API files. Inputs let you parameterize requests so callers can supply different values. Outputs extract fields from the response for use in test flows.
+
+## Files
+
+| File | Description |
+|---|---|
+| `get_with_outputs.mmt` | Bracket-path extraction — `body[name]`, `body[tags][0]`, `body[tags].length` |
+| `get_dot_notation.mmt` | Dot-notation extraction — `body.nested.enabled`, `body.nested.items[0].key` |
+| `post_with_inputs_outputs.mmt` | Inputs + bracket-path outputs from the echoed response, including accessor examples like `<<i:username[0]>>` |
+| `post_regex_outputs.mmt` | Regex extraction — `body[/"username":"(.*?)"/]`, `headers[/pattern/]`, and `'body[/\sResult:\s(.*)\s\[\s/]'` |
+
+## How to use
+
+### In VS Code
+
+1. Open any `.mmt` file in this folder.
+2. Click **Run** — inputs use their default values; outputs appear in the response panel.
+3. Change input values in the **Inputs** section of the editor before running.
+
+### With the CLI
+
+```sh
+npx testlight run examples/intermediate/01_api_inputs_outputs/get_with_outputs.mmt
+npx testlight run examples/intermediate/01_api_inputs_outputs/post_with_inputs_outputs.mmt
+```
+
+Override inputs from the command line:
+
+```sh
+npx testlight run examples/intermediate/01_api_inputs_outputs/post_with_inputs_outputs.mmt \
+  -e username=bob -e role=viewer
+```
+
+## Key concepts
+
+- **`inputs`** — declare parameters with default values. Reference them with `i:name` (entire value) or `<<i:name>>` (inline in a string).
+- **Accessors on variables** — append `[0]`, `[0:3]`, or `.field` to `i:` / `e:` tokens when you need only part of the value.
+- **`outputs`** — three extraction styles:
+  - **Bracket path** — `body[nested][items][0][key]` for structured access
+  - **Dot notation** — `body.nested.items[0].key` as a shorter alternative
+  - **Regex** — `regex "field":"(.*?)"` to capture from raw response text (first capture group wins)
+- Outputs can be chained into subsequent steps in a test flow using `${step_id.output_name}`.
+
+See [API docs](../../../docs/files/api/index.md#inputs) and [API docs — outputs](../../../docs/files/api/index.md#outputs) for full details.

package/dist/examples/intermediate/01_api_inputs_outputs/get_dot_notation.mmt

@@ -0,0 +1,14 @@
+type: api
+title: Extract nested fields (dot notation)
+description: |-
+  Extract deeply nested values from a JSON response.
+  Use dot notation for object traversal and bracket notation for arrays.
+outputs:
+  is_enabled: body.nested.enabled
+  nested_count: body.nested.count
+  first_item_key: body.nested.items.0.key
+  second_item_value: body.nested.items.1.value
+  items_length: body.nested.items.length
+url: https://test.mmt.dev/json
+method: get
+format: json

package/dist/examples/intermediate/01_api_inputs_outputs/get_with_outputs.mmt

@@ -0,0 +1,10 @@
+type: api
+title: Get user info
+description: Fetch a JSON payload and extract fields as outputs
+outputs:
+  name: body[name]
+  tags: body[tags]
+  first_tag: body[tags][0]
+url: https://test.mmt.dev/json
+method: get
+format: json

package/dist/examples/intermediate/01_api_inputs_outputs/post_regex_outputs.mmt

@@ -0,0 +1,24 @@
+type: api
+title: Extract with regex
+description: |
+  Extract values from the response using regular expressions.
+  Use `body[/pattern/]` or `body./pattern/` to extract from the body.
+  Use `headers[/pattern/]` or `headers./pattern/` to extract from headers.
+  If the regex contains a capture group `(...)`, the first group is returned;
+  otherwise the entire match is returned.
+inputs:
+  username: alice
+  email: alice@example.com
+outputs:
+  extracted_name: body[/"username":\s"(alice)"/]
+  extracted_email: body[/"email":\s"([^"]+)"/]
+  timestamp_date: body./"timestamp":\s"(\d{4}-\d{2}-\d{2})/
+  content_type: headers[/application\/json/]
+  result_code: 'body[/\sResult:\s(.*)\s\[\s/]'
+url: https://test.mmt.dev/echo
+method: post
+format: json
+body:
+  username: i:username
+  email: i:email
+  note: " Result: AB12 [ "

package/dist/examples/intermediate/01_api_inputs_outputs/post_with_inputs_outputs.mmt

@@ -0,0 +1,20 @@
+type: api
+title: Post echo with inputs
+description: Send dynamic values via inputs, including sliced values, and extract them from the echoed response
+inputs:
+  username: alice
+  role: admin
+outputs:
+  echoed_username: body[body][username]
+  echoed_role: body[body][role]
+  echoed_initial: body[body][user_initial]
+  echoed_role_short: body[body][role_short]
+  method: body[method]
+url: https://test.mmt.dev/echo
+method: post
+format: json
+body:
+  username: i:username
+  role: i:role
+  user_initial: <<i:username[0]>>
+  role_short: <<i:role[0:3]>>

package/dist/examples/intermediate/02_websocket/README.md

@@ -0,0 +1,44 @@
+# WebSocket Example
+
+This example shows how to define **WebSocket APIs** with inputs and outputs in `.mmt` files, and how to test them in a flow.
+
+## Files
+
+| File | Description |
+|---|---|
+| `ws_echo.mmt` | Send a text message to a WS echo server and capture the reply |
+| `ws_json_echo.mmt` | Send a JSON object over WS with inputs, extract fields from the echoed response |
+| `ws_test.mmt` | Test flow that calls both WS APIs and verifies echoed values |
+
+## How to use
+
+### In VS Code
+
+1. Open any `.mmt` file in this folder.
+2. Click **Run** to connect, send, and see the response.
+3. Change input values before running to send different messages.
+
+### With the CLI
+
+```sh
+npx testlight run examples/intermediate/02_websocket/ws_echo.mmt
+npx testlight run examples/intermediate/02_websocket/ws_json_echo.mmt
+npx testlight run examples/intermediate/02_websocket/ws_test.mmt
+```
+
+Override inputs:
+
+```sh
+npx testlight run examples/intermediate/02_websocket/ws_echo.mmt -e greeting="Hi there"
+```
+
+## Key concepts
+
+- **`protocol: ws`** — use WebSocket instead of HTTP. Also inferred automatically from `ws://` or `wss://` URLs.
+- **`body`** — the message sent to the server. Can be a string or JSON object.
+- **`inputs`** — parameterize the message content with `i:name`.
+- **`outputs`** — extract fields from the server's reply using `body[field]` bracket paths.
+- **`format: json`** — parse the reply as JSON so bracket-path outputs work.
+- No `method` field is needed for WebSocket APIs.
+
+See [API docs](../../../docs/files/api/index.md#websocket) for full details.

package/dist/examples/intermediate/02_websocket/ws_echo.mmt

@@ -0,0 +1,11 @@
+type: api
+title: WebSocket echo
+description: Connect to a WebSocket echo server and send a message
+inputs:
+  greeting: Hello from Multimeter!
+outputs:
+  reply: body
+url: wss://test.mmt.dev/ws
+protocol: ws
+format: text
+body: i:greeting

package/dist/examples/intermediate/02_websocket/ws_json_echo.mmt

@@ -0,0 +1,16 @@
+type: api
+title: WebSocket JSON echo
+description: Send a JSON object over WebSocket and extract fields from the echoed response
+inputs:
+  username: alice
+  action: ping
+outputs:
+  echoed_user: body.username
+  echoed_action: body.action
+url: wss://test.mmt.dev/ws
+protocol: ws
+format: json
+body:
+  username: i:username
+  action: i:action
+  timestamp: c:epoch

package/dist/examples/intermediate/03_graphql/README.md

@@ -0,0 +1,10 @@
+# GraphQL Examples
+
+These examples show how to define and test GraphQL APIs using `.mmt` files.
+
+## Files
+
+| File | Description |
+|------|------------|
+| `graphql_query.mmt` | Simple GraphQL query |
+| `graphql_mutation.mmt` | GraphQL mutation with variables |

package/dist/examples/intermediate/03_graphql/graphql_query.mmt

@@ -0,0 +1,16 @@
+type: api
+title: GraphQL query
+description: Fetch a list of countries using a public GraphQL API
+outputs:
+  first_country: body.data.countries.0.name
+url: https://countries.trevorblades.com/graphql
+protocol: graphql
+graphql:
+  operation: |
+    query {
+      countries {
+        code
+        name
+        capital
+      }
+    }

package/dist/examples/intermediate/03_graphql/graphql_variables.mmt

@@ -0,0 +1,25 @@
+type: api
+title: GraphQL query with variables
+description: Fetch a single country by code using GraphQL variables
+inputs:
+  country_code: BR
+outputs:
+  country_name: body.data.country.name
+  capital: body.data.country.capital
+url: https://countries.trevorblades.com/graphql
+protocol: graphql
+graphql:
+  operation: |
+    query GetCountry($code: ID!) {
+      country(code: $code) {
+        name
+        capital
+        currency
+        languages {
+          name
+        }
+      }
+    }
+  variables:
+    code: i:country_code
+  operationName: GetCountry

package/dist/examples/intermediate/04_grpc/README.md

@@ -0,0 +1,10 @@
+# gRPC Examples
+
+These examples show how to define and test gRPC services using `.mmt` files.
+
+## Files
+
+| File | Description |
+|------|------------|
+| `grpc_unary.mmt` | Simple unary gRPC call |
+| `grpc_server_stream.mmt` | Server-streaming gRPC call |

package/dist/examples/intermediate/04_grpc/grpc_server_stream.mmt

@@ -0,0 +1,15 @@
+type: api
+title: gRPC server streaming
+description: Open a server-streaming gRPC call to receive multiple responses
+outputs:
+  first_message: body[0].message
+url: grpc://localhost:50051
+protocol: grpc
+grpc:
+  proto: ./greeter.proto
+  service: greeter.Greeter
+  method: SayHelloStream
+  stream: server
+  message:
+    name: Multimeter
+    count: 3

package/dist/examples/intermediate/04_grpc/grpc_unary.mmt

@@ -0,0 +1,13 @@
+type: api
+title: gRPC unary call
+description: Send a unary gRPC request to a greeting service
+outputs:
+  greeting: body.message
+url: grpc://localhost:50051
+protocol: grpc
+grpc:
+  proto: ./greeter.proto
+  service: greeter.Greeter
+  method: SayHello
+  message:
+    name: Multimeter

package/dist/examples/intermediate/05_api_documentation/README.md

@@ -0,0 +1,33 @@
+# Example 5 — API Documentation
+
+Generate a Swagger-like HTML documentation page from your `.mmt` API files.
+
+## What's inside
+
+| File | Description |
+|---|---|
+| `api/get_users.mmt` | GET endpoint — list users |
+| `api/post_create_user.mmt` | POST endpoint — create a user |
+| `api/ws_notifications.mmt` | WebSocket — subscribe to notifications |
+| `markdown_api/search_products.mmt` | GET — description with `> headings`, **bold**, *italic*, pipe tables, and bullet lists |
+| `markdown_api/submit_order.mmt` | POST — description with numbered lists, status-code table, `ref` link, and `<<i:>>`/`<<o:>>` annotations |
+| `markdown_api/health_check.mmt` | GET — entire description loaded from a Markdown file via `ref overview.md#health-check` |
+| `markdown_api/overview.md` | Shared Markdown file referenced by `ref` links in API descriptions |
+| `document.mmt` | Doc file that renders all the above as an interactive HTML page |
+
+## How to use
+
+1. Open `document.mmt` in VS Code with the Multimeter extension installed.
+2. The editor renders a searchable HTML page listing all three APIs.
+3. Expand any row to see URL, inputs, outputs, body, and parameter descriptions.
+4. Click the **Try** button on any endpoint to send a live request from the browser.
+
+## Concepts demonstrated
+
+- **`type: doc`** scans a folder for `type: api` files and renders them
+- **`html.triable: true`** adds interactive Try buttons to every endpoint
+- **`<<i:param>>` / `<<o:param>>` annotations** in API `description` fields become parameter documentation columns
+- **Markdown in descriptions** — `**bold**`, `*italic*`, `` `code` ``, `> headings`, bullet/numbered lists, pipe tables
+- **`ref` file links** — `ref overview.md#section` loads description from a shared Markdown file
+- **`services`** grouping — organize APIs into logical groups in the rendered doc
+- Mixed protocols (HTTP GET, HTTP POST, WebSocket) in a single doc

package/dist/examples/intermediate/05_api_documentation/api/get_users.mmt

@@ -0,0 +1,13 @@
+type: api
+title: List users
+description: |
+  Returns a list of all users in the system.
+
+  <<o:name>> The user's display name
+  <<o:tags>> Array of tags associated with the user
+outputs:
+  name: body[name]
+  tags: body[tags]
+url: https://test.mmt.dev/json
+method: get
+format: json

package/dist/examples/intermediate/05_api_documentation/api/post_create_user.mmt

@@ -0,0 +1,25 @@
+type: api
+title: Create user
+description: |
+  Create a new user account with the given details.
+
+  <<i:username>> The desired username (3-20 characters)
+  <<i:email>> User's email address
+  <<i:role>> User role: `admin`, `editor`, or `viewer`
+
+  <<o:echoed_username>> The username as confirmed by the server
+  <<o:method>> HTTP method used (should be POST)
+inputs:
+  username: alice
+  email: alice@example.com
+  role: editor
+outputs:
+  echoed_username: body[body][username]
+  method: body[method]
+url: https://test.mmt.dev/echo
+method: post
+format: json
+body:
+  username: i:username
+  email: i:email
+  role: i:role

package/dist/examples/intermediate/05_api_documentation/api/ws_notifications.mmt

@@ -0,0 +1,18 @@
+type: api
+title: Notification stream
+description: |
+  Subscribe to real-time notifications via WebSocket.
+  Send a JSON message to start receiving events.
+
+  <<i:channel>> The notification channel to subscribe to
+  <<o:echoed_channel>> The channel name echoed back by the server
+inputs:
+  channel: alerts
+outputs:
+  echoed_channel: body.channel
+url: wss://test.mmt.dev/ws
+protocol: ws
+format: json
+body:
+  action: subscribe
+  channel: i:channel

package/dist/examples/intermediate/05_api_documentation/document.mmt

@@ -0,0 +1,17 @@
+type: doc
+title: Test Server APIs
+description: |-
+  Auto-generated documentation for the sample APIs that call
+  [test.mmt.dev](https://test.mmt.dev).
+
+  Open this file in VS Code with the Multimeter extension to render an
+  interactive HTML doc view.
+services:
+  - name: API with descriptions
+    description: How having description will be placed in final documents.
+    sources:
+      - api
+  - name: API with reference to markdown descriptions
+    description: How we can reference to md as description.
+    sources:
+      - markdown_api

package/dist/examples/intermediate/05_api_documentation/markdown_api/health_check.mmt

@@ -0,0 +1,6 @@
+type: api
+title: Health check
+description: overview.md#health-check
+url: https://test.mmt.dev/json
+method: get
+format: json

package/dist/examples/intermediate/05_api_documentation/markdown_api/overview.md

@@ -0,0 +1,77 @@
+# Markdown API Overview
+
+Shared documentation referenced by API files using `ref` links.
+Each API's `description` field uses `ref overview.md#section` to load its docs from here.
+
+## Search Products
+
+Search the product catalog by keyword.
+
+> Request Format
+
+Pass `q` as a query parameter with the search term.
+The server echoes back the full request including **headers** and **query string**.
+
+> Response Fields
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `method` | string | HTTP method used |
+| `path` | string | Request path |
+| `body` | object | Echoed request body (empty for GET) |
+
+> Notes
+
+- Results are sorted by *relevance* by default
+- Use `sort=price` to sort by price ascending
+- Maximum **100** results per page
+
+## Submit Order
+
+Place a new order with the given items.
+
+> Authentication
+
+Requires a **Bearer token** in the `Authorization` header.
+See the [Authentication](#authentication) section below for details.
+
+> Request Body
+
+The body must be a JSON object with the following fields:
+
+1. `product_id` — the product to order
+2. `quantity` — number of units (min: 1, max: 99)
+3. `note` — optional note for the seller
+
+> Status Codes
+
+| Code | Meaning |
+| --- | --- |
+| `200` | Order placed successfully |
+| `400` | Validation error (missing fields) |
+| `401` | Missing or invalid auth token |
+| `422` | Product out of stock |
+
+## Authentication
+
+All endpoints under the **Orders** service require a `Bearer` token in the `Authorization` header:
+
+```
+Authorization: Bearer <your-token>
+```
+
+Tokens are issued by the `/auth` endpoint and expire after **1 hour**.
+Contact your admin to request API credentials.
+
+## Health Check
+
+Returns basic system information as JSON.
+
+Use this endpoint to verify connectivity before running tests.
+A `200` response with a valid JSON body indicates the server is healthy.
+
+**Expected fields:**
+- `id` — always `1`
+- `name` — service name
+- `version` — current version string
+- `tags` — capability tags

package/dist/examples/intermediate/05_api_documentation/markdown_api/search_products.mmt

@@ -0,0 +1,15 @@
+type: api
+title: Search products
+description: overview.md#search-products
+inputs:
+  q: multimeter
+outputs:
+  method: body[method]
+  path: body[path]
+url: https://test.mmt.dev/echo
+query:
+  q: i:q
+  sort: relevance
+  limit: "20"
+method: get
+format: json

package/dist/examples/intermediate/05_api_documentation/markdown_api/submit_order.mmt

@@ -0,0 +1,18 @@
+type: api
+title: Submit order
+description: overview.md#submit-order
+inputs:
+  product_id: prod_9281
+  quantity: 3
+outputs:
+  echoed_product: body[body][product_id]
+  method: body[method]
+url: https://test.mmt.dev/echo
+method: post
+format: json
+headers:
+  Authorization: Bearer demo-token-xyz
+body:
+  product_id: i:product_id
+  quantity: i:quantity
+  note: Please gift-wrap

package/dist/examples/intermediate/06_imports/README.md

@@ -0,0 +1,92 @@
+# Imports
+
+Demonstrates the different ways to import and call API and test files in `.mmt`.
+
+## Files
+
+| File | Description |
+|---|---|
+| `multimeter.mmt` | Project root marker — enables `+/` imports |
+| `apis/echo_api.mmt` | Echo API definition used as an import target |
+| `apis/greet_api.mmt` | Greet API definition in the same folder |
+| `tests/test_api.mmt` | Test that imports APIs using relative paths and calls each one |
+| `test_relative.mmt` | Imports `tests/test_api.mmt` using a relative path |
+| `test_root_import.mmt` | Imports `tests/test_api.mmt` using a `+/` project root path |
+
+## Import path styles
+
+`.mmt` files support three styles of import paths:
+
+```yaml
+import:
+  # 1. Relative path — resolved from the current file's directory
+  echo: ../apis/echo_api.mmt
+  greet: ./apis/greet_api.mmt
+
+  # 2. Project root path (+/) — resolved from the directory containing multimeter.mmt
+  shared: +/tests/test_api.mmt
+
+  # 3. Absolute path — used as-is (rarely needed)
+  abs: /full/path/to/file.mmt
+```
+
+### When to use each style
+
+| Style | Best for |
+|---|---|
+| Relative (`echo_api.mmt`, `../apis/greet.mmt`) | Files near the current file. Simple, no setup needed. |
+| Project root (`+/path/file.mmt`) | Shared files across different folders. Requires a `multimeter.mmt` marker file at the project root. |
+| Absolute (`/full/path/file.mmt`) | Rare cases where files live outside the project. |
+
+## What you can import
+
+| Type | Extension | Used with |
+|---|---|---|
+| API definition | `.mmt` (`type: api`) | `call` step |
+| Test flow | `.mmt` (`type: test`) | `call` step (runs as a nested test) |
+| CSV data | `.csv` | `data` + `for` steps |
+| JavaScript module | `.js` / `.cjs` / `.mjs` | `js` steps |
+| Mock server | `.mmt` (`type: server`) | `run` step |
+
+## How to use
+
+### In VS Code
+
+1. Open `test_relative.mmt` to see a test imported with a relative path.
+2. Open `test_root_import.mmt` to see the same test imported with a `+/` project root path.
+3. Click **Run** on either file — the imported test calls two APIs and checks the responses.
+
+### With the CLI
+
+Run using relative import:
+
+```sh
+npx testlight run examples/intermediate/06_imports/test_relative.mmt --env-file examples/intermediate/06_imports/multimeter.mmt
+```
+
+Run using project root import:
+
+```sh
+npx testlight run examples/intermediate/06_imports/test_root_import.mmt --env-file examples/intermediate/06_imports/multimeter.mmt
+```
+
+Run the inner API test directly:
+
+```sh
+npx testlight run examples/intermediate/06_imports/tests/test_api.mmt --env-file examples/intermediate/06_imports/multimeter.mmt
+```
+
+## Key concepts
+
+- **`import`** — declares aliases for external files. The alias becomes a callable reference.
+- **`call`** — invokes an imported API or test by its alias. Must be the first field in the step. Outputs from the call are stored in the `id` variable.
+- **`+/` prefix** — resolves the path from the nearest parent directory containing `multimeter.mmt`. This lets files in different folders share imports without fragile relative paths.
+- **Nested test calls** — when a test imports and calls another test, the child test's steps run inline. Checks and outputs propagate to the parent.
+- **`multimeter.mmt`** — a `type: env` file that marks the project root. It can also define shared variables and presets.
+- **`|-` for multiline descriptions** — use `|-` (literal block, strip trailing newline) for multiline description fields.
+
+## Next steps
+
+- See [Simple Test](../../basic/02_simple_test/) for a direct basic test example.
+- See [CSV Data Driven Test](../09_csv_data_driven_test/) for CSV data imports.
+- See [Environment Presets](../10_environment_presets/) for environment presets in `multimeter.mmt`.

package/dist/examples/intermediate/06_imports/apis/echo_api.mmt

@@ -0,0 +1,13 @@
+type: api
+title: Echo API
+description: Posts a message and echoes it back
+inputs:
+  message: hello world
+outputs:
+  echoed_message: body.body.message
+  status_code: status
+url: https://test.mmt.dev/echo
+method: post
+format: json
+body:
+  message: i:message

package/dist/examples/intermediate/06_imports/apis/greet_api.mmt

@@ -0,0 +1,13 @@
+type: api
+title: Greet API
+description: Posts a name and returns a greeting
+inputs:
+  name: world
+outputs:
+  greeted_name: body.body.name
+  status_code: status
+url: https://test.mmt.dev/echo
+method: post
+format: json
+body:
+  name: i:name

package/dist/examples/intermediate/06_imports/multimeter.mmt

@@ -0,0 +1,5 @@
+type: env
+variables:
+  base_url: 
+    local: http://localhost:8787
+    cloud: https://test.mmt.dev

package/dist/examples/intermediate/06_imports/test_relative.mmt

@@ -0,0 +1,15 @@
+type: test
+title: Import test with relative paths
+description: |-
+  Imports a test using a relative path and calls it.
+  The imported test itself imports and calls APIs, so this demonstrates
+  nested test-to-test imports with relative path resolution.
+import:
+  api_test: ./tests/test_api.mmt
+steps:
+  - call: api_test
+    id: result
+    title: Run API test (relative import)
+    inputs:
+      message: from relative import
+      name: relative call