API TEST KIT

Overview

API TEST KIT is a powerful tool designed to simplify API testing. This package provides features for generating REST API clients from OpenAPI JSON/YAML files, custom-built API assertions for response validation, and built-in logging for all requests and responses.

$3

- Generates REST API Client using OpenAPI Specification JSON/YAML files.
- Supports Playwright, Axios, and SuperTest as HTTP client libraries.
- Custom-built assertions for API response validation.
- Built-in logging to capture request and response details.

Installation

``sh
npm install api-test-kit
`

Usage

$3

The API Client Generator CLI tool generates API client code from an OpenAPI JSON specification, allowing customization of various aspects like HTTP library selection, naming conventions, and output directory.

#### CLI Command

`sh
npx apiBuilder --help
`

#### CLI Options

`
Usage: apiBuilder [options]

Options:
--json Path to the OpenAPI JSON specification file
--serviceName Custom name for the generated API client (e.g., MyAPIClient)
-l, --libraryName HTTP client library to use for API requests (default: Axios)
--classNameKey Determines the class name for API endpoints (default: "tags")
--methodNameKey Determines the method name for API operations (default: "operationId")
-f, --featureName Generate the API client for a specific feature or endpoint
-o, --output Output directory where the generated API client files will be saved
-h, --help Display help for command
`

#### Example

Generating a Covid API service client from https://covid-api.com/api/:

`sh
npx apiBuilder --json https://covid-api.com/api/docs/api-docs.json --serviceName Covid --output covid-api
`

#### Output Directory Structure

`
covid-api
├── Covid.ts
├── CovidApiManager.ts
└── endpoints
├── RegionApi.ts
├── ReportApi.ts
└── schema.json
`

$3

#### Example API Request

`ts
const covidClient = new CovidClient('https://covid-api.com');
covidClient.loggingManager.enable();

const response = await covidClient.region.regions({
headers: {
'X-CSRF-TOKEN': '',
},
params: {
per_page: 20,
},
});

await response.verifyResponse({
status: 200,
statusText: 'OK',
'time[?]less_than': 5000,
data: {
current_page: 1,
data: [
{ iso: 'AUS', name: 'Australia' },
{ iso: 'USA', name: 'US' },
],
},
schema: 'Region-regions-200',
});
`

$3

`ts
{
// timeout specifies the number of milliseconds before the request times out.
timeout: number, // default is 30000

// headers are custom headers to be sent
headers: { [key: string]: string},

// params are the URL parameters to be sent with the request
params: { [key: string]: string | number | boolean } | URLSearchParams,

// data is the data to be sent as the request body
data: Serializable,

// form data to be sent with the request
formData: { [key: string]: string | number | boolean } | FormData
}
`

$3

`ts
{
// url used when sending the request
url: string,

// method used for the request
method: string,

// time in ms took to process the request
time: number,

// status is the HTTP status code from the server response
status: number,

// statusText is the HTTP status message from the server response
statusText: string,

ok: boolean,

// An object with all the response HTTP headers associated with this response.
headers: { [key: string]: string},

// Returns the JSON representation of response body.
json(): Promise,

// Returns the text representation of response body.
text(): Promise,

// Returns the request and response log
log(): string[],

// Verifies the response received from the server with the expected response
verifyResponse(expectedResponse: {
status?: number;
statusText?: string;
time?: number;
headers?: { [key: string]: string };
data?: { [key: string]: any };
schema?: string;
[key: string]: any;
}): Promise
}
`

Available Methods

$3

- Enable logging:
Logging once enabled at the client it cannot be enabled again. The log file is generated with the current datetime.

`ts
covidClient.loggingManager.enable();
`

- Custom logging configuration:

`ts
covidClient.loggingManager.enable({ level: 'info', filepath: './logs', filename: 'api-log.txt' });
`

- Disable logging:

`ts
covidClient.loggingManager.disable();
`

- Log a message:

`ts
covidClient.loggingManager.log('Custom log message');
`

$3

- Add header at session level:

`ts
covidClient.headerManager.add({ Authorization: 'Bearer token' });
`

- Remove a header:

`ts
covidClient.headerManager.remove('Authorization');
`

- Get session-level headers:

`ts
covidClient.headerManager.get();
`

$3

`ts
covidClient.apiManager.apiStats();
`

$3

Ensure to disable the logging before generating the HTML report

`ts
await covidClient.loggingManager.disable();

generateHtmlReport(covidClient.loggingManager.getLogFile());
`

Assertions for API response validation

`ts
await response.verifyResponse({
status: 200,
statusText: 'OK',
'time[?]less_than': 5000,
data: {
'current_page[?]defined': 1,
'data[?]contains': [
{ iso: 'AUS', name: 'Australia' },
{ iso: 'USA', name: 'US' },
],
},
schema: 'Region-regions-200',
});
`

$3

| Operator | Description | Example |
| -------------- | ----------------------------- | ------------------------------------- |
| equal_to | Exact string match (Default) | 'city[?]equal_to': 'Sydney' |
| ignore_case | Case-insensitive string match | 'city[?]ignore_case': 'SYDney' |
| not_equal_to | String inequality | 'city[?]not_equal_to': 'Melbourne' |
| contains | Substring check | 'city[?]contains': 'Syd' |
| not_contains | Substring absence | 'city[?]not_contains': 'Mel' |
| match | Regular expression match | 'city[?]match': 'Syd.*' |
| defined | Field exists | 'city[?]defined': 'Sydney' |
| not_defined | Field absent | 'city_name[?]not_defined': 'Sydney' |

$3

| Operator | Description | Example |
| ----------------------- | -------------------------- | --------------------------------- |
| equal_to | Numeric equality (Default) | 'id[?]equal_to': 1234 |
| not_equal_to | Numeric inequality | 'id[?]not_equal_to': 4567 |
| less_than | Less than | 'id[?]less_than': 10000 |
| less_than_equal_to | Less than equal to | 'id[?]less_than_equal_to': 9999 |
| greater_than | Greater than | 'id[?]greater_than': 0 |
| greater_than_equal_to | Greater than equal to | 'id[?]greater_than_equal_to': 1 |
| is_between | Range check | 'id[?]is_between': '1 to 9999' |
| defined | Field exists | 'id[?]defined': 1234 |
| not_defined | Field absent | 'id[?]not_defined': 1234 |

$3

| Operator | Description | Example |
| -------------- | -------------------------- | -------------------------------- |
| equal_to | Boolean equality (Default) | 'status[?]equal_to': true |
| not_equal_to | Boolean inequality | 'status[?]not_equal_to': false |
| defined | Field exists | 'status[?]defined': true |
| not_defined | Field absent | 'status[?]not_defined': true |

$3

| Operator | Description | Example |
| ----------------- | ------------------------------------ | -------------------------------------------------------------- |
| equal_to | Exact array match | 'cities[?]equal_to': ['Sydney', 'Melbourne', 'Perth'] |
| contains | Contains elements in array (Default) | 'cities[?]contains': ['Sydney', 'Melbourne'] |
| contains_once | Contains elements exactly once | 'cities[?]contains_once': ['Sydney', 'Melbourne'] |
| not_contains | Does not contain elements | 'cities[?]not_contains': ['Brisbane', 'Adelaide'] |
| ignore_sequence | Array match irrespective of sequence | 'cities[?]ignore_sequence': ['Melbourne', 'Perth', 'Sydney'] |
| defined | Field exists | 'cities[?]equal_to': [] |
| not_defined | Field absent | 'cities[?]not_defined': [] |

$3

| Operator | Description | Example |
| ------------- | ------------------------------------------------ | -------------------------------------------------------------------- |
| equal_to | Exact object match | 'data[?]equal_to': { name: 'Trish', city: 'Sydney' , status: true} |
| contains | Contains specified key/value in object (Default) | 'data[?]contains': { name: 'Trish', city: 'Sydney'} |
| defined | Field exists | 'data[?]equal_to': {} |
| not_defined | Field absent | 'data[?]not_defined': {} |

$3

- is - Verifies the data type of a field

`
Available Data Types:
'string',
'number',
'boolean',
'array',
'object',
'array_of_string',
'array_of_number',
'array_of_boolean',
'array_of_object'

Example:
'data[?]is': 'object'
``

Conclusion

API TEST KIT streamlines API testing by offering client generation, assertions, and logging, making it an essential tool for developers working with REST APIs. For further details and advanced configurations, refer to the official documentation.