npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

spec-mate

v1.0.0

Published

A powerful, flexible, and easy-to-use API testing framework for Node.js.

Downloads

7

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

  • 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.