spec-mate
v1.0.0
Published
A powerful, flexible, and easy-to-use API testing framework for Node.js.
Downloads
7
Maintainers
Keywords
Readme
Spec Mate
spec-mate is a powerful API testing framework developed by S25Digital, designed to help developers streamline the process of testing and validating APIs. With support for advanced assertions, customizable hooks, and seamless integration with tools like Nock, spec-mate makes it easy to test even the most complex APIs.
Table of Contents
- Features
- Installation
- Usage
- Comprehensive Assertions
- Advanced Features
- Test Example with Nock
- Hooks
- Contribution
- About S25Digital
- License
Features
- Comprehensive API Testing: Test all aspects of an API response, from headers and status codes to cookies and JSON bodies.
- Built-in Assertions: Easily validate JSON paths, headers, status codes, cookies, and more.
- Custom Assertions: Extend functionality by adding user-defined assertions.
- Mocking Support: Easily integrate with Nock to mock HTTP requests and responses.
- Integration with Chai: Works seamlessly with Chai assertions, including
chai-json-schema
. - Hooks for Custom Logic: Allows you to add pre- and post-request logic via hooks.
Installation
To install spec-mate, use npm or yarn:
npm install spec-mate
Additionally, you’ll need some supporting libraries for testing:
npm install chai axios nock --save-dev
Usage
Example: Basic API Test
import { SpecMate } from 'spec-mate';
const api = new SpecMate('https://api.example.com');
async function runTest() {
await api.request('/users')
.withMethod('GET')
.expectStatus(200)
.expectHeader('Content-Type', 'application/json')
.expectJsonPath('results[0].name', 'John Doe')
.run();
}
runTest();
This example demonstrates a simple GET
request with validations for the response status code, content type, and a specific JSON path.
Comprehensive Assertions
SpecMate offers a range of built-in assertions to validate various aspects of an API response. Below is a detailed list of available assertions with usage examples.
1. Status Code Assertions
Ensure that the response has the expected status code.
.expectStatus(200)
2. Header Assertions
Check if a specific header exists and has the expected value.
.expectHeader('Content-Type', 'application/json')
3. Header Existence Assertions
Ensure a specific header is present in the response.
.expectHeaderExists('Content-Type')
Ensure a specific header is absent in the response.
.expectHeaderNotExists('X-Powered-By')
4. JSON Path Assertions
Validate that a value exists at a specific path within the JSON response body.
.expectJsonPath('results[0].name', 'John Doe')
5. JSON Length Assertions
Check the length of an array or object at a specific JSON path.
.expectJsonLength('results', 3)
6. Body Contains Assertion
Ensure the response body contains a specific text.
.expectBodyContains('user')
7. Body Regex Assertion
Ensure that the response body matches a regular expression.
.expectBodyMatches(/"name": "John Doe"/)
8. Content Type Assertion
Verify that the Content-Type
header matches a specific type.
.expectContentType('application/json')
9. Status Code Range Assertion
Ensure that the status code falls within a specific range.
.expectStatusInRange(200, 299)
10. Redirect Assertion
Check if the response status is a redirection (3xx).
.expectRedirect()
11. Cookie Assertions
Check for the existence and value of a cookie.
.expectCookie('session', 'abc123')
Ensure that a cookie contains a specific partial value.
.expectCookieContains('session', 'abc')
12. Custom Assertions
Create your own assertions with custom logic. This is helpful for more advanced testing scenarios.
.customAssertion((response) => {
expect(response.data.results).to.have.lengthOf.above(1);
});
Advanced Features
Custom Assertions
In addition to the built-in assertions, SpecMate allows you to define your own custom assertions to extend the testing capabilities.
api.request('/users')
.withMethod('GET')
.customAssertion((response) => {
expect(response.data).to.have.property('results').with.length.greaterThan(1);
})
.run();
Cookie Assertions
Check for the existence or value of cookies in the response.
.expectCookie('session', 'abc123')
.expectCookieContains('session', 'abc')
Test Example with Nock
Here’s an example of using spec-mate with Nock to mock API responses for testing purposes:
import { SpecMate } from 'spec-mate';
import nock from 'nock';
describe('API Test Example with Nock', () => {
const api = new SpecMate('https://api.example.com');
beforeEach(() => {
nock.cleanAll();
nock.disableNetConnect();
});
it('should mock and validate a GET request', async () => {
// Mock GET /users API request
nock('https://api.example.com')
.get('/users')
.reply(200, {
results: [{ name: 'John Doe' }, { name: 'Jane Doe' }]
});
await api.request('/users')
.withMethod('GET')
.expectStatus(200)
.expectJsonPath('results[0].name', 'John Doe')
.run();
});
});
Hooks
SpecMate provides hooks that allow you to run custom logic before or after a request is made.
Before Request Hook
Use the beforeRequest
hook to modify request headers, such as adding authentication tokens.
api.on('beforeRequest', (context) => {
context.headers['Authorization'] = `Bearer some-token`;
});
After Request Hook
Run logic after the request is completed, such as logging the response.
api.on('afterRequest', (response) => {
console.log('Response received:', response.data);
});
License
This project is licensed under the MIT License. See the LICENSE file for more details.
About Us
spec-mate is developed and maintained by S25Digital
Related Repository:
- mock-mate
For seamless API testing with mocked responses, check out mock-mate, another tool developed by S25Digital. mock-mate is designed to make API mocking simpler and more flexible, providing an easy way to create mock APIs that integrate perfectly with your spec-mate tests.
With mock-mate, you can:
- Create mock APIs based on OpenAPI specs.
- Pre-configure expected responses, headers, and status codes for different scenarios.
- Seamlessly integrate with spec-mate to test APIs in isolation without needing a live backend.
Use mock-mate in combination with spec-mate to create a complete testing suite for validating API functionality in controlled environments.