WireMock Recording

This guide provides step-by-step instructions for recording and saving API mocks into a WireMock Cloud project using the WireMock CLI and httpyac. You'll learn how to generate HTTP files, configure test scenarios, record API calls, and save comprehensive mocks including error cases.

On this page

• 📚 Overview
• 📋 Prerequisites
• 🚀 Installation Steps
• 📄 Creating HTTP Files with Copilot
• ⚙️ Configuring HTTP Variables and Routes
• 🎬 Recording API Calls
• 🏃 Executing HTTP Files with httpyac
• 💾 Saving Mocks to WireMock Cloud
• 🔍 Troubleshooting
• 📖 Next Steps

📚 Overview

Recording API mocks allows you to capture real API interactions and replay them in your development and testing environments. This process involves:

• 🎯 Generate HTTP Files: Use GitHub Copilot to create comprehensive REST client files
• ⚙️ Configure Variables: Set up dynamic variables and error scenarios
• 🎬 Record Sessions: Capture API calls using WireMock CLI proxy recording
• 🏃 Execute Requests: Run all scenarios using httpyac CLI
• 💾 Save Mocks: Store captured interactions in WireMock Cloud projects

📋 Prerequisites

Before you begin, ensure you have:

• ✅ WireMock CLI installed (npm install -g @wiremock/cli)
• ✅ httpyac CLI installed (npm install -g httpyac)
• ✅ WireMock Cloud Account with appropriate permissions
• ✅ API Endpoints to record (accessible from your machine)
• ✅ GitHub Copilot enabled in VS Code (for HTTP file generation)

🚀 Installation Steps

Step 1: Install WireMock CLI

Open your terminal and install the WireMock CLI globally:

npm install -g @wiremock/cli

Verify the installation:

wiremock --version

Step 2: Install httpyac CLI

Install httpyac CLI globally:

npm install -g httpyac

Verify the installation:

httpyac --version

📄 Creating HTTP Files with Copilot

Use GitHub Copilot to generate comprehensive HTTP files that cover all your API endpoints and scenarios.

Step 1: Create the HTTP File

Create a new file with a .http or .rest extension:

api-tests.http

Step 2: Use Copilot to Generate Requests

Use GitHub Copilot to generate comprehensive HTTP requests for your API. Here are effective prompts to get the best results:

⚠️ NOTE The prompt samples below are generalized and should not be used as a copy/paste into Copilot, but instead as a starting point. The prompt content should be unique to the circumstances surounding the API you wish to record mocks for.

Sample Prompt 1: Based on Controller Code

When you have access to your API controller code:

Prompt: "Analyze the UserController.cs file and generate a comprehensive .http file that tests all endpoints. Include success cases and error scenarios (400, 401, 403, 404, 500). Use global variables for baseUrl, authToken, and userId. Ensure each request has proper headers and request bodies for POST/PUT operations. Include tests for invalid data, unauthorized access, and non-existent resources."

Sample Prompt 2: Based on Minimal API Endpoints

For APIs built with minimal API pattern:

Prompt: "Based on the minimal API endpoints defined in Program.cs, create a complete .http file with all CRUD operations. Include global variables (@baseUrl, @authToken) at the top before any ### sections. Generate error test cases for each endpoint including malformed JSON (400), invalid authentication (401/403), missing resources (404), and server errors (500). Add response extraction variables using @name for chaining requests."

Sample Prompt 3: Based on OpenAPI/Swagger Documentation

When you have OpenAPI specification files:

Prompt: "Using the swagger.json/openapi.yaml file, generate a comprehensive .http file that covers all documented endpoints. Include global variables for configuration and ensure proper variable scoping. For each endpoint, create both success and failure scenarios. Include edge cases like empty request bodies, invalid data types, oversized payloads, and authentication edge cases. Use httpyac syntax with @name annotations for response chaining."

Sample Prompt 4: Based on Deployed API Documentation

For APIs with accessible Swagger UI:

Prompt: "I have a REST API with Swagger documentation at https://api.example.com/swagger. Create a .http file that tests all endpoints shown in the Swagger UI. Include global variables (@baseUrl = https://api.example.com/api/v1) and authentication tokens. Generate comprehensive test scenarios including: success paths (2xx), client errors (400, 401, 403, 404, 409, 422), and server errors (500, 503). Ensure error scenarios test realistic failure cases like duplicate resources, validation failures, and rate limiting."

Sample Prompt 5: Complete API Test Suite

For comprehensive coverage:

Prompt: "Create a complete .http file for testing a [describe your API type, e.g., 'e-commerce user management API']. Structure it with global variables at the top, then organized sections for each resource. Include:

• Global variables: @baseUrl, @authToken, @contentType
• Authentication tests (valid/invalid tokens)
• CRUD operations for each resource
• Error scenarios: 400 (bad request), 401 (unauthorized), 403 (forbidden), 404 (not found), 409 (conflict), 422 (validation), 500 (server error)
• Edge cases: empty payloads, malformed JSON, special characters, boundary values
• Response chaining using @name annotations
• Comments explaining each test scenario"

Enhanced Prompt Template

Use this template and customize it for your specific API:

Prompt: "Generate a comprehensive .http file for [YOUR_API_DESCRIPTION] based on [CONTROLLER_FILE/OPENAPI_FILE/SWAGGER_URL]. Requirements:

Structure:

• Global variables at top (before any ### sections): @baseUrl, @authToken, @userId, @contentType
• Organized sections with ### headers for each resource/endpoint group

Coverage:

• All CRUD operations (GET, POST, PUT, DELETE, PATCH)
• Authentication scenarios (valid/invalid/missing tokens)
• Success responses (200, 201, 204)
• Client errors: 400 (validation), 401 (auth), 403 (forbidden), 404 (not found), 409 (conflict), 422 (unprocessable)
• Server errors: 500 (internal), 502 (bad gateway), 503 (unavailable)

Error Test Cases:

• Invalid JSON syntax
• Missing required fields
• Invalid data types/formats
• Boundary value testing
• Duplicate resource creation
• Operations on non-existent resources

Advanced Features:

• Response extraction with @name annotations
• Variable chaining between requests
• Dynamic data generation
• Proper HTTP headers and content types"

Tips for Better Copilot Results

When crafting your prompts, include these details for better results:

📋 Context Information:

• Mention the specific file types you're working with (controllers, minimal APIs, OpenAPI specs)
• Include the programming framework (.NET Core, Node.js, Python FastAPI, etc.)
• Specify authentication methods (JWT, API keys, OAuth, etc.)

🎯 Structure Requirements:

• Explicitly request global variables before ### sections
• Ask for organized sections by resource or functionality
• Request response chaining using @name annotations

🔍 Error Coverage:

• Be specific about error codes you want to test
• Request realistic error scenarios for your domain
• Ask for boundary and edge case testing

💡 Example Context Additions:

"This is a .NET Core Web API with JWT authentication"
"The API uses minimal APIs with validation attributes"
"Authentication is via Bearer tokens with role-based access"
"The API includes file upload endpoints"
"Rate limiting is implemented on certain endpoints"

Example Generated HTTP File Structure

# User Management API Tests
# This file contains comprehensive tests for user management endpoints

# Global variables (accessible to all requests)
@baseUrl = {{$dotenv %baseUrl}}
@authToken = {{$dotenv %authToken}}
@userId = {{$dotenv %userId}}

### Authentication Test
GET {{baseUrl}}/auth/validate
Authorization: Bearer {{authToken}}

### Get All Users (Success)
GET {{baseUrl}}/users
Authorization: Bearer {{authToken}}
Accept: application/json

### Get User by ID (Success)
GET {{baseUrl}}/users/{{userId}}
Authorization: Bearer {{authToken}}
Accept: application/json

### Get User by ID (404 - Not Found)
GET {{baseUrl}}/users/99999
Authorization: Bearer {{authToken}}
Accept: application/json

### Create User (Success)
POST {{baseUrl}}/users
Authorization: Bearer {{authToken}}
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john.doe@example.com",
  "role": "user"
}

### Create User (400 - Bad Request)
POST {{baseUrl}}/users
Authorization: Bearer {{authToken}}
Content-Type: application/json

{
  "name": "",
  "email": "invalid-email"
}

### Create User (403 - Forbidden)
POST {{baseUrl}}/users
Authorization: Bearer invalid-token
Content-Type: application/json

{
  "name": "Jane Doe",
  "email": "jane.doe@example.com"
}

### Server Error Simulation (500)
GET {{baseUrl}}/users/trigger-error
Authorization: Bearer {{authToken}}

### Update User
PUT {{baseUrl}}/users/{{userId}}
Authorization: Bearer {{authToken}}
Content-Type: application/json

{
  "name": "John Updated",
  "email": "john.updated@example.com"
}

### Delete User
DELETE {{baseUrl}}/users/{{userId}}
Authorization: Bearer {{authToken}}

⚙️ Configuring HTTP Variables and Routes

Step 1: Set Up Environment Variables

Create a .env file in your project root:

# API Configuration
baseUrl=https://api.example.com/v1
authToken=your-api-token-here
userId=123

# Alternative environments
# baseUrl=https://staging-api.example.com/v1
# baseUrl=http://localhost:3000/api/v1

Step 2: Configure Global Variables

Add global variables at the top of your HTTP file (before any ### sections):

# Global Variables (accessible to all requests)
@baseUrl = https://api.example.com/v1
@contentType = application/json
@authToken = your-api-token-here

### Get User Request
# @name getUserResponse
GET {{baseUrl}}/users/1
Authorization: Bearer {{authToken}}

### Create User Request
# @name createUserResponse
POST {{baseUrl}}/users
Content-Type: {{contentType}}
Authorization: Bearer {{authToken}}

{
  "name": "Test User"
}

### Use Response Data in Next Request
# Extract data from previous response (section-scoped variable)
@newUserId = {{createUserResponse.response.body.$.id}}

GET {{baseUrl}}/users/{{newUserId}}
Authorization: Bearer {{authToken}}

Alternative: Section-Scoped Variables

You can also define variables within specific sections for section-specific use:

### User Management Section
# Variables scoped to this section only
@sectionBaseUrl = https://api.example.com/v1/users
@testUserId = 123

GET {{sectionBaseUrl}}/{{testUserId}}

### Admin Section
# Different variables scoped to this section
@adminBaseUrl = https://api.example.com/v1/admin
@adminToken = admin-specific-token

GET {{adminBaseUrl}}/users
Authorization: Bearer {{adminToken}}

Step 3: Add Error Scenarios

Ensure your HTTP file includes comprehensive error testing:

### Error Scenarios

### 400 Bad Request - Invalid JSON
POST {{baseUrl}}/users
Content-Type: application/json

{
  "name": "",
  "email": "not-an-email",
  "age": "invalid-age"
}

### 401 Unauthorized - Missing Token
GET {{baseUrl}}/users
# No Authorization header

### 403 Forbidden - Invalid Token
GET {{baseUrl}}/users
Authorization: Bearer invalid-token-123

### 404 Not Found - Non-existent Resource
GET {{baseUrl}}/users/999999
Authorization: Bearer {{authToken}}

### 429 Rate Limit (if applicable)
### Repeat request rapidly
GET {{baseUrl}}/users
Authorization: Bearer {{authToken}}

### 500 Server Error - Trigger server error
GET {{baseUrl}}/admin/trigger-error
Authorization: Bearer {{authToken}}

🎬 Recording API Calls

Step 1: Start WireMock CLI Recording

Start the recording session with WireMock CLI. You can either record to a new project or an existing one:

Option A: Record to New Project (Interactive)

wiremock record https://api.example.com

This will prompt you to create a new WireMock Cloud project at the end of the session.

Option B: Record to Existing Project

First, get your WireMock Cloud project ID from the URL in the WireMock Cloud dashboard (e.g., 33eye3l9):

wiremock record https://api.example.com --to=cloud:33eye3l9

Option C: Record with Custom Port

wiremock record https://api.example.com --to=cloud:33eye3l9 --reverse-proxy-port=8080

Step 2: Update HTTP File for Recording

Modify your HTTP file to point to the WireMock proxy (default: localhost:8000). Update your global variables:

# Global variables for recording (accessible to all requests)
@baseUrl = http://localhost:8000
@authToken = your-api-token-here
@userId = 123

### Authentication Test
GET {{baseUrl}}/auth/validate
Authorization: Bearer {{authToken}}

### Get All Users (Success)
GET {{baseUrl}}/users
Authorization: Bearer {{authToken}}
Accept: application/json

# Rest of your HTTP requests remain the same...

Step 3: Configure Batch Recording (Optional)

For large recording sessions, configure batch imports:

wiremock record https://api.example.com --to=cloud:33eye3l9 --max-batch-requests=50

This will import mocks in batches of 50 requests to prevent memory issues and data loss.

🏃 Executing HTTP Files with httpyac

Step 1: Execute All Requests

Run all HTTP requests in your file:

httpyac send api-tests.http --all

Step 2: Execute with Environment Variables

httpyac send api-tests.http --all --env production

Step 3: Execute with Verbose Output

httpyac send api-tests.http --all --verbose

Step 4: Execute with JSON Output

For CI/CD or automated scenarios:

httpyac send api-tests.http --all --json

Step 5: Execute Specific Requests

Execute requests by name or line number:

# Execute by name
httpyac send api-tests.http --name "Get All Users"

# Execute by line number
httpyac send api-tests.http --line 25

Step 6: Execute with Custom Variables

Override variables at runtime:

httpyac send api-tests.http --all --var baseUrl=http://localhost:8000 --var authToken=test-token

💾 Saving Mocks to WireMock Cloud

Step 1: Complete Recording Session

After executing all your HTTP requests through httpyac:

1. Return to the WireMock CLI terminal
2. Press Enter to stop the recording session
3. Choose or confirm the destination WireMock Cloud project

Step 2: Verify Saved Mocks

1. Open WireMock Cloud dashboard
2. Navigate to your project
3. Review captured stubs in the Stubs section
4. Verify all scenarios were captured (success and error cases)

Step 3: Organize and Clean Up Mocks

Review and organize your captured mocks:

• ✅ Check Success Scenarios: Ensure all 2xx responses are captured
• ✅ Verify Error Scenarios: Confirm 4xx and 5xx responses are recorded
• ✅ Review Request Matching: Adjust matchers if needed
• ✅ Add Descriptions: Document each stub for clarity
• ✅ Remove Duplicates: Clean up redundant mocks

Example Mock Verification Checklist

✅ GET /users (200 OK)
✅ GET /users/123 (200 OK)
✅ GET /users/999999 (404 Not Found)
✅ POST /users (201 Created)
✅ POST /users (400 Bad Request - Invalid Data)
✅ POST /users (403 Forbidden - Invalid Token)
✅ PUT /users/123 (200 OK)
✅ DELETE /users/123 (204 No Content)
✅ GET /admin/trigger-error (500 Internal Server Error)

🔍 Troubleshooting

Common Issues and Solutions

Issue: Recording Session Not Capturing Requests

Solution: Ensure your HTTP file is pointing to the correct proxy URL:

# Correct proxy URL (default WireMock CLI port)
@baseUrl = http://localhost:8000

Issue: Authentication Errors During Recording

Solution: Verify your API tokens and credentials:

### Test authentication first
GET {{baseUrl}}/auth/validate
Authorization: Bearer {{authToken}}

Issue: httpyac Command Not Found

Solution: Reinstall httpyac globally:

npm uninstall -g httpyac
npm install -g httpyac

Issue: SSL Certificate Errors

Solution: Use the --insecure flag with httpyac:

httpyac send api-tests.http --all --insecure

Issue: Missing Error Scenarios in Mocks

Solution: Ensure your HTTP file explicitly tests error conditions:

### Force 404 error
GET {{baseUrl}}/nonexistent-endpoint

### Force 400 error with invalid data
POST {{baseUrl}}/users
Content-Type: application/json
{
  "invalid": "data"
}

Debug Recording Issues

1. Check WireMock CLI Output: Look for errors in the recording terminal
2. Verify Proxy Traffic: Ensure requests are going through localhost:8000
3. Test Individual Requests: Run single requests to isolate issues
4. Check Network Connectivity: Verify the target API is accessible

📖 Next Steps

After successfully recording your API mocks:

1. Host WireMock CLI - Learn how to use recorded mocks in your Aspire applications
2. WireMock Documentation - Explore advanced WireMock features
3. httpyac Documentation - Master advanced HTTP testing scenarios
4. Configure CI/CD Integration - Automate mock recording in your deployment pipeline
5. Set up Mock Versioning - Implement version control for your API mocks

Advanced Recording Scenarios

• Multi-domain Recording: Record from multiple API endpoints simultaneously
• Mutual TLS Recording: Record from APIs requiring client certificates
• Advanced Configuration: Use configuration files for complex recording scenarios
• Non-interactive Recording: Automate recording in CI/CD pipelines

Best Practices

• 📝 Document Your Mocks: Add clear descriptions to each recorded stub
• 🔄 Regular Updates: Keep your mocks synchronized with API changes
• 🧪 Test Coverage: Ensure all API scenarios are covered including edge cases
• 🔒 Security: Avoid recording sensitive data in production environments
• 📊 Monitoring: Track mock usage and performance in your applications