Metadata-Version: 2.4
Name: matimo-bruno
Version: 0.1.0
Summary: Matimo provider — Bruno API testing tools (collections, requests, imports, reports)
License: MIT
Keywords: agents,ai,api-testing,bruno,matimo,tools
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.11
Requires-Dist: matimo-core<0.2.0,>=0.1.0
Description-Content-Type: text/markdown

# matimo-bruno

Bruno CLI tools for Matimo — Enable AI agents to autonomously manage, execute, and validate API test collections.

## 📦 Installation

```bash
pip install matimo-bruno
```

## 🚀 Quick Start

### Python

```python
from matimo import Matimo

matimo = await Matimo.init()

# List all collections in workspace
collections = await matimo.execute('bruno_list_collections', {
    'workspace_path': './collections'
})

# Get collection metadata before running
info = await matimo.execute('bruno_get_collection_info', {
    'collection_path': './collections/payment-api'
})

# Run entire collection
result = await matimo.execute('bruno_run_collection', {
    'collection_path': './collections/payment-api',
    'environment': 'staging',
    'report_path': './reports/staging-results.json'
})

# Run single request for debugging
response = await matimo.execute('bruno_run_request', {
    'collection_path': './collections/auth',
    'request_name': 'Login',
    'environment': 'staging'
})

# Bootstrap from OpenAPI spec
imported = await matimo.execute('bruno_import_openapi', {
    'spec_source': 'https://api.example.com/openapi.json',
    'output_directory': './collections',
    'collection_name': 'Generated API Tests'
})

# Create new collection
created = await matimo.execute('bruno_create_collection', {
    'collection_path': './collections/new-service',
    'collection_name': 'New Service Tests'
})
```

## 📋 Available Tools

### 1. `bruno_run_collection`
Execute a Bruno API collection with configurable environments, data files, and reporting.

**Parameters:**
- `collection_path` (required) — Path to collection file or directory
- `environment` — Environment name (dev, staging, prod)
- `env_file` — Path to environment file override
- `data_file` — CSV/JSON data file for data-driven testing
- `iteration_count` — Number of iterations to run
- `delay_ms` — Delay between requests
- `tags` — Comma-separated tags (run requests with ALL tags)
- `exclude_tags` — Comma-separated tags (skip requests with ANY tags)
- `tests_only` — Run only requests with tests/assertions
- `bail_on_failure` — Stop on first failure
- `parallel` — Run requests in parallel
- `sandbox_mode` — JavaScript execution mode ('safe' or 'developer')
- `report_format` — Report format (json, junit, html)
- `report_path` — Path to write report file

**Returns:** Collection execution results, summary, and report path

### 2. `bruno_run_request`
Execute a single request for targeted debugging and validation.

**Parameters:**
- `collection_path` (required) — Collection directory
- `request_name` (required) — Request name to execute
- `environment` — Environment name override
- `env_file` — Environment file override
- `sandbox_mode` — JavaScript execution mode

**Returns:** Request/response details and assertion results

### 3. `bruno_list_collections`
Discover all collections in a workspace.

**Parameters:**
- `workspace_path` (required) — Workspace directory
- `filter` — Filter by collection name (substring)

**Returns:** Array of collection metadata

### 4. `bruno_get_collection_info`
Introspect collection structure before execution.

**Parameters:**
- `collection_path` (required) — Collection path

**Returns:** Collection structure, requests, environments, variables

### 5. `bruno_import_openapi`
Bootstrap a collection from OpenAPI 3.0 specification.

**Parameters:**
- `spec_source` (required) — Path or URL to OpenAPI spec
- `output_directory` (required) — Where to create collection
- `collection_name` — Collection name
- `collection_format` — 'bru' or 'opencollection'
- `group_by` — Group by 'tags' or 'path'
- `insecure` — Skip TLS verification

**Returns:** Collection path and metadata

### 6. `bruno_create_collection`
Create a new empty collection scaffold.

**Parameters:**
- `collection_path` (required) — Collection creation path
- `collection_name` (required) — Collection name

**Returns:** Creation status and path

## 🔄 Agent Workflows

### Autonomous Test Execution
```
Agent discovers spec → import_openapi → set environment → run_collection → parse results
```

### Multi-Environment Validation
```
list_collections → for each environment: set_env + run_collection → compare results
```

### Targeted Debugging
```
get_collection_info → run_request (single endpoint) → analyze response
```

### Data-Driven Testing
```
run_collection with CSV file → multiple iterations → aggregate metrics
```

## 🔐 Authentication

Tools use environment variables for credentials. Bruno CLI manages environment setup — tools wrap CLI execution.

## 📖 Prerequisites

- **Bruno CLI** installed globally: `pnpm install -g @usebruno/cli`
- **Python** 3.11+
- Bruno collections in `.bru` format or OpenAPI specs

## 🤝 Integration

Works with:
- **LangChain** — Convert to StructuredTool
- **CrewAI** — Convert to BaseTool
- **MCP** — Expose via JSON-RPC to Claude / other MCP clients
- **Native** — Direct SDK usage

## 📝 License

MIT
