npm package: @redredchen01/api-testing
Description: CLI toolkit for API testing — requests, collections, environments, assertions, mock server
Latest version: 1.0.0

# @foundry/api-testing

> CLI toolkit for API testing — requests, collections, environments, assertions, mock server

[![npm version](https://img.shields.io/npm/v/@foundry/api-testing.svg)](https://www.npmjs.com/package/@foundry/api-testing)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Install

### CLI Tool

```bash
npm install -g @foundry/api-testing
```

### Claude Code Skill

Download `.skill` file from [GitHub Releases](https://github.com/redredchen01/skill-foundry/releases):

```bash
claude skill install api-testing.skill
```

## Quick Start

```bash
# Send a GET request
api-testing request --url https://api.example.com/users

# POST JSON with Bearer auth
api-testing request --method POST \
  --url https://api.example.com/users \
  --json '{"name":"Alice"}' \
  --bearer mytoken123

# Assert the response
api-testing request --url https://api.example.com/users/1 \
  | api-testing assert --status 200 --json-path .name

# Start a mock server
api-testing mock --port 3001 --response ./fixture.json
```

## Commands

| Command | Description |
|---------|-------------|
| `request` | Send HTTP requests (GET/POST/PUT/DELETE/PATCH) via curl |
| `collection` | Save, list, run, and delete named request collections |
| `env` | Manage named API environments (BASE_URL, AUTH_TOKEN, API_KEY) |
| `assert` | Assert response status code, body content, JSON path values |
| `mock` | Start a local mock HTTP server with configurable responses |
| `history` | View and manage recent request history |

## Examples

### Environments

```bash
api-testing env set production BASE_URL=https://api.example.com
api-testing env set production AUTH_TOKEN=secret
api-testing env use production
api-testing env show
```

### Collections

```bash
api-testing collection save get-users --method GET --url https://api.example.com/users
api-testing collection list
api-testing collection run get-users
api-testing collection delete get-users
```

### Assertions

```bash
# Pipe from request to assert
api-testing request --url https://api.example.com/health \
  | api-testing assert --status 200 --contains '"ok":true'

# Check a specific JSON field exists
api-testing request --url https://api.example.com/users/1 \
  | api-testing assert --json-path .id --json-path .email
```

### Mock Server

```bash
# Default response on port 3000
api-testing mock

# Custom port and response file
api-testing mock --port 8080 --response ./mock-data.json --status 200

# Simulate slow API (500ms delay)
api-testing mock --delay 500
```

### History

```bash
api-testing history list
api-testing history show 1
api-testing history clear
```

## As Claude Skill

After installing, describe what you want in natural language. For example:

> "Send a POST request to https://api.example.com/users with JSON body"
> "Start a mock HTTP server on port 3001"
> "Test this endpoint and check the response is 200"
> "Save this API request as a collection called 'create-user'"

## Requirements

- `bash` 3.2+
- `curl` (for `request` and `collection run`)
- `node` (for JSON pretty-printing, `mock` server, `assert --json-path`)

## License

MIT