Mock Scripts is an advanced feature that requires JavaScript knowledge. For most use cases, Smart Mock and Mock Expectations are sufficient. You can skip this article if you're just getting started with API mocking.
1. What Are Mock Scripts?#
Mock Scripts are JavaScript code snippets that run when a mock request is received. They allow you to:Access request data: Read path parameters, query parameters, headers, and body
Modify response data: Change the Smart Mock-generated response before it's returned
Maintain relationships: Ensure response data matches request parameters (e.g., response ID matches request ID)
Add logic: Implement conditional logic, calculations, and data transformations
When to Use Mock Scripts#
Use Mock Scripts when you need:Request-response consistency: The response ID should match the ID in the request URL
Logical relationships: Response fields depend on request parameters (e.g., age affects adoption fee)
Dynamic calculations: Compute values based on request data
Conditional responses: Return different data based on request conditions
2. How Mock Scripts Work#
1.
Smart Mock generates an initial mock response based on your API spec
2.
Mock Script runs and can access both the request ($$.mockRequest) and the generated response ($$.mockResponse)
3.
Script modifies the response as needed
4.
Final response is returned to the client
Available Objects#
$$.mockRequest: Access request data (parameters, headers, body)
$$.mockResponse: Access and modify the mock response
3. Example 1: Matching Request ID in Response#
Let's start with a simple example: ensuring the pet ID in the response matches the ID in the request URL.Scenario#
When you request GET /pets/pet_123, the response should include "id": "pet_123"βnot a random ID generated by Smart Mock.Step 1: Open the Mock Tab#
1.
Open the GET /pets/{id} endpoint in your Pet Store API
3.
Scroll down to find the "Mock Script" section
Step 2: Enable and Write the Script#
1.
Turn on the script toggle
2.
Write the following script:
Step 3: Test the Mock#
1.
Use the mock URL with a specific pet ID: GET /pets/pet_1Nv0FGQ9RKHgCVdK
2.
The response will now include "id": "pet_1Nv0FGQ9RKHgCVdK" instead of a random ID
3.
The self link will also use the correct ID
{
"id": "pet_abc123xyz",
"name": "Luna",
"species": "DOG",
...
}
{
"id": "pet_1Nv0FGQ9RKHgCVdK",
"name": "Luna",
"species": "DOG",
"links": {
"self": "https://api.petstoreapi.com/v1/pets/pet_1Nv0FGQ9RKHgCVdK"
},
...
}
Let's create a more complex example: ensuring pagination metadata matches the request parameters.Scenario#
For GET /pets?page=2&limit=10, the response should include:pagination.page = 2 (from request)
pagination.limit = 10 (from request)
pagination.totalPages calculated based on total items
Script#
Result#
When you request GET /pets?page=2&limit=10, the response will have:{
"data": [...],
"pagination": {
"page": 2,
"limit": 10,
"totalItems": 45,
"totalPages": 5
},
"links": {
"self": "https://api.petstoreapi.com/v1/pets?page=2&limit=10",
"prev": "https://api.petstoreapi.com/v1/pets?page=1&limit=10",
"next": "https://api.petstoreapi.com/v1/pets?page=3&limit=10",
"last": "https://api.petstoreapi.com/v1/pets?page=5&limit=10"
}
}
5. Example 3: Conditional Logic Based on Request#
You can also use Mock Scripts to return different responses based on request conditions.Scenario#
For GET /pets/{id}, if the pet ID starts with pet_test_, return a special test pet with predictable data.Script#
Result#
Request: GET /pets/pet_test_123 β Returns predictable test data
Request: GET /pets/pet_1Nv0FGQ9RKHgCVdK β Returns Smart Mock data with matching ID
6. Common Use Cases#
Accessing Request Data#
Modifying Response Data#
7. Key Takeaways#
Mock Scripts allow you to customize Smart Mock responses with JavaScript
Request-response consistency: Ensure response data matches request parameters
Dynamic logic: Implement calculations, conditional logic, and data transformations
Only works with Smart Mock: Mock Scripts don't apply to Mock Expectations or response examples
Access request data: Use $$.mockRequest to read parameters, headers, and body
Modify response data: Use $$.mockResponse to update the mock response before it's returned
Powerful tool: Enables realistic mock responses that maintain logical relationships
Mock Scripts give you the flexibility to create intelligent mock responses that maintain data consistency and logical relationships. Combined with Smart Mock, Mock Expectations, and Cloud Mock, you have a complete toolkit for API mocking in Apidog.