stadius

Utilities for easier and explorative testing

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
stadius
1.0.12a month ago4 months agoMinified + gzip package size for stadius in KB

Readme

Welcome to Stadius
Reliability Rating Code Smells Vulnerabilities Bugs Security Rating
A set of easy to use, batteries included libraries to make your life easier when testing and exploring APIs. Stadius's intent is to be used against live, running instances. With different configurations tests can be run against different environments (e.g. vs DEV, UAT, PRD) Staduis works with jest's test and assertion runner.

Main functionalities

Client Library

Stadius offers a request library based on ``supertest request``, but enhances it with verbose logging, dotenv support and configuration goodies(see below) a few examples:
import { client } from "stadius";

await client.GET("https://my.api.dev", {})
const response = await client.POST(
      "https://my.api.dev/user", // url
      {'My Header': '123}, // headers
      { foo: "Bar" } // body
    );

const response = await client.PUT(
      "https://my.api.dev/user", // url
      {'My Header': '123}, // headers
      { foo: "Bar" } // body
    );

const response = await client.DELETE(
      "https://my.api.dev/user", // url
      {'My Header': '123}, // headers
    );

Instance Clients

Sometimes you may want to have several different clients with Base Urls and repeatable headers. For these cases stadius exports it's class stadius:
import { Stadius } from "stadius";

const customClient = new Staidus("myBaseUrl", {"X-Common-Header": "Headers that will be added to each request" });
// NOTE: common headers are added **before** the request headers. You can override them for a single request if needed.

Parametrized API Running

Stadius helps you write more declarative tests and less code by offering a wrapper arround the ``test.each``.
Calling the ``runTests` method inside a `describe`` block will run each test. You can view the type of the test here
The gist is that the Request's fields are mandatory, where as you can check as little (for example the statusCode) or as much (statusCode, headers, body) of the response as you want.
This is the most minimal example:
describe('Test Runner Example test suite', () => {
  runTests([
    {
      name: 'Sanity check - not found',
      url: 'https://swapi.dev/api/people/131311',
      request: {method: 'GET', body: {}, headers: {}},
      response: {statusCode: 404},
    },
  ]);
});

Upon executing these tests you will execute the following request:
++++++++++++++++++++++++++++++++++++++++++++++++++
 REQUEST:
 {
  url: 'https://swapi.dev/api/people/131311',
  method: 'GET',
  body: {}
}
 RESPONSE:
 {
  status: 404,
  body: {
    detail: 'Not found'
  }
}
 ==================================================

On test failure the name passed in the test is used:
FAIL  myfile.test.ts
 ● Test Runner › Executing test: Sanity check - not found

   expect(received).toEqual(expected) // deep equality

   Expected: 201
   Received: 404

You can view more examples in this test suite

Swagger Validation

Stadius also offers a swagger validation library. It parses an OpenAPI v3 document and offers methods that validate the request and response against the swagger definitions. This will allow to easily verify that the face of the API -> which is the Open API validation, with the actual behavior of the API
Please navigate to ``examples/api-example`` for a demo.

Test Generation

Stadius has a test generation module. Simply put it will generate one or more test suites based on a schema you pass. By itself this functionality is useful because the user can declare request/response pairs and can generate and regenerate tests on demand for different environments, etc. For a basic example please navigate to the test
The functionality is better when combined with an external source. Please navigate to this example to see an example with generating tests from an excel document.

Utility Functions

Field hiding

Setting the ``HIDDEN_FIELDS` environment variable to a comma separated list of field names and then using the `hideFields`` utility function will replace all occurrences of these keys in an object and replace them with a supplied value, default xxx.
const example = {a: 12, b: {a: 13}};
hideFields(body); // after this call example will equal: {a: 'xxx', b: {a: 'xxx'}};
More examples

Configuration

Stadius uses environment variables for the configuration. For complete list of options please visit ``config.ts`` but the two most important ones are:
VERBOSE - if set to true headers will also be logged. By default they are {}
SILENT - if set to true no log output will be made
AUTH - if set the value will be added as Authorization header

dotenv is integrated with stadius