@9paradox/apitester

v0.1.9

Published

7 months ago

A simple rest api testing package. Crafted with easy to use method call and method chaining, so you can write clean api testing automation scripts in javascript and typescript.

Downloads

0High
0Medium
0Low

9paradox

apitester api-testing testing rest-api typescript javascript nodejs

apitester

A simple rest api testing package. Crafted with easy to use method call and method chaining, so you can write clean api testing automation scripts in javascript and typescript.

🛠️ This project is still in alpha stage and there might be breaking changes in stable release. 🛠️

Features

Easily test entire api workflows.
Define testing steps directly in json file.
Log request and response.
Capture time and performance.
Load testcase data.
Load request and data templates.
Query data easily with jmespath or jsonata.
Extend functionality using custom functions.

Installation

Install into an new or existing javascript/typescript project.

npm i @9paradox/apitester

Usage

Initial step is to create a testcase using one of the following way:
- apitester.createTestCase function to write testcase through code.
- apitester.createTestCaseFromJsonFile function to build testcase from json file.
- apitester.getJsonTestCasesFromFolder function to get all json testcases from a folder.
The testcase can perform multiple steps/actions.
Each step/action requires input data. Some of the steps can use output data from previous step as input.
Finally we call test() function to start executing the testcase, which returns a Promise.
- In case of apitester.getJsonTestCasesFromFolder, we use apitester.runTestCases(testcases) to execute multiple testcases.

Simple example to get started with apitester.createTestCase.

//simple_test.js
const { apitester } = require('@9paradox/apitester');

const testcase = apitester.createTestCase({
  title: 'verify todos endpoint returns status 200',
});

testcase
  //step 1. get results form /todos
  .get('https://jsonplaceholder.typicode.com/todos/')

  //step 2. verify the status is success
  .pickAndVerify({ query: 'status', expected: 200 })

  //perform the test
  .test()
  .then((testResult) => {
    console.log('Testcase success:- ', testResult.success);
    if (!testResult.success) {
      console.log('Testcase failed:- ', testResult.error);
      console.log('Testcase steps:- ', testResult.steps);
    }
  })
  .catch((err) => console.log(err));

to run the file

node simple_test.js

We can use apitester in any nodejs test project such as jest or xv. There are some more examples in the examples folder. PRs adding more examples are very welcome!

Try online

Check out these demo testcase to get started with apitester.

Method Reference

`apitester.createTestCase(..)`

Create new testcase.

const testcase = apitester.createTestCase({...}: TestCaseOptions);

TestCaseOptions

`apitester.createTestCaseFromJsonFile(..)`

Create new testcase from json test-case file.

const testcase = apitester.createTestCaseFromJsonFile(
  'path-to-file/test-case.json'
);

Make sure the json test case file follows TestCaseOptions schema.

{
  "title": "running apitester from example-test-case.json file",
  "steps": [
    {
      "action": "get",
      "inputData": "https://jsonplaceholder.typicode.com/todos/"
    },
    {
      "action": "pickAndVerify",
      "inputData": {
        "query": "status",
        "expected": 200,
        "toBe": "=="
      }
    }
  ]
}

`apitester.getJsonTestCasesFromFolder(..)` and `apitester.runTestCases(..)`

We can test multiple json testcase from a given folder.
Testcase file name must end with .test.json, for example simple-testcase.test.json, or else custom file extension list can be provided to apitester.getJsonTestCasesFromFolder(..)
apitester.runTestCases(..) returns MultiTestCaseResult.

//example folder with testcase
//  path-to/
//    -- json-testcases/
//        -- my-testcase.test.json
//        -- other_scenario.test.json

const testCases = apitester.getJsonTestCasesFromFolder(
  'path-to/json-testcases'
  //,['.test.json', '.apitester'] //custom file extensions (optional)
);

const multiTestCaseResult = await apitester.runTestCases(testCases);

if (!multiTestCaseResult.success) {
  console.log('Testcases failed: ' + multiTestCaseResult.failedTestCases);
}

apitester.runTestCases(testCases, callback) also supports callback (data: TestCaseCallbackData) => Promise<void>.

Quester - vscode extension

Create and run apitester testcases directly in vscode now. Install Quester for vscode from Visual Studio Code marketplace.

Quester - vscode extension

apitester-creator

Now easily create testcases with the online drag-and-drop tool - apitester-creator.

apitester-creator

Export json testcases and run them using apitester.getJsonTestCasesFromFolder(..) and apitester.runTestCases(..).

Action/Step methods

Once a new testcase is created, we can perform multiple steps/actions and finally call test() method to execute the test.

Type Reference

StepOptions

Create steps from JSON object.

| Parameter | Type | Required | Description | | :---------- | :----------- | :------- | :----------------------------------------------------------------------------------------------------------- | | action | ActionName | yes | Action name such as get,pickAndVerify etc. | | inputData | any | yes | Input data for the action. Check method reference. |

CallbackData

User provided callback function which is called before and after each step.

TestCaseCallbackData

User provided callback function which is called before and after each testcase running with apitester.runTestCases(...).

GetOptions

Create GetOptions using one of the following type.

PostOptions

Create PostOptions using one of the following type.

BuildDataOptions

Query data form different steps and merge into one object.

| Parameter | Type | Required | Description | | :-------- | :------------ | :------- | :-------------------------------------------------- | | queries | QueryData[] | yes | Array of queries to merge data from multiple steps. |

QueryData

FormatTemplateOptions

Create FormatTemplateOptions using one of the following type.

| Type | Description | | :----------------------------------------------------------------------------------------------- | :--------------------------------------- | | string | Template filepath. | | {'filePath' : string, 'outputDataFormat' : string or number or 'boolean or object} | Template filepath and render output type | | undefined | To take type from last step. |

PickAndVerifyOptions

Perform json query to pick data from last step and verify the data against expected data.

ToBe

Assertion to perform against expected data. == is default.

equal , == , notEqual , != , greaterThan , > , greaterThanOrEqual , >= , lessThan , < , lessThanOrEqual , <= , in , notIn , contains

VerifyOptions

Create VerifyOptions using one of the following type.

| Type | Description | | :------------------------------------------------------- | :--------------------------- | | string | string data. | | {'expected' : any, 'toBe' : ToBe or undefined} | Expected data to be verified |

VerifyTimeTakenOptions

Verify time taken by last step.

CustomFnOptions

User provided function to run as a step.

| Parameter | Type | Required | Description | | :--------- | :--------------- | :------- | :------------------------------- | | stepType | StepType | yes | Type of step. | | fn | CustomFunction | yes | Filepath of the javascript file. |

CustomFunction structure

//custom function input parameter and return type structure
myFunction = async (testCase: TestCase, currentStep: Step, lastStep: Step) => {
	return {
		inputData: any;
		outputData: any;
		verification?: VerificationResult; //required when the step is Verification type
	}
}

CustomFnFromOptions

User provided function from a external file to run as a step. The user function should follow CustomFunction definition.

An example of a custom function from a external javascript file.

//function should follow CustomFunction structure.
async function myCustomFunction(testCase, currentStep, lastStep) {
  var output = testCase.data('delectus_aut_autem');
  output = output.toUpperCase();
  var result = {
    inputData: lastStep.outputData,
    outputData: output,
  };
  return result;
}

//should follow exporting the functionName
module.exports.myCustomFunction = myCustomFunction;

StepType

Used to indicate step operation type.

VerificationResult

Return type for verification step.

QueryLang

Enum to identify which json query library to use.

Step

Structure of a step.

| Parameter | Type | Description | | :----------- | :-------------------------- | :------------------------------------------------------------- | | index | number | Step number starting from 1. | | type | StepType | Type of step. | | action | ActionName | Step/Action method name. | | inputData | any | Input data/parameters provided to the action method. | | outputData | any | Output/return data from the action method. | | verified | Optional<boolean> | Indicator if the step has been verified against the assertion. | | startedAt | string | Date time stamp of starting the step. | | endedAt | string | Date time stamp of ending the step. | | timeTaken | { ms: number; s: number } | Time taken to execute the step. |

TestCaseResult

Return type for testcase test() method.

MultiTestCaseResult

Structure of multi testcase execution.

Error

Structure of testcase error.

Roadmap

Refactor code to support plugin architecture
Add more actions
Update docs
Code refactor
Add more examples
Add support for XML.

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

apitester

Features

Table of Contents

Installation

Usage

Try online

Method Reference

apitester.createTestCase(..)

TestCaseOptions

apitester.createTestCaseFromJsonFile(..)

apitester.getJsonTestCasesFromFolder(..) and apitester.runTestCases(..)

Quester - vscode extension

apitester-creator

Action/Step methods

Type Reference

StepOptions

CallbackData

TestCaseCallbackData

GetOptions

PostOptions

BuildDataOptions

QueryData

FormatTemplateOptions

PickAndVerifyOptions

ToBe

VerifyOptions

VerifyTimeTakenOptions

CustomFnOptions

CustomFunction structure

CustomFnFromOptions

StepType

VerificationResult

QueryLang

Step

TestCaseResult

MultiTestCaseResult

Error

Roadmap

License

`apitester.createTestCase(..)`

`apitester.createTestCaseFromJsonFile(..)`

`apitester.getJsonTestCasesFromFolder(..)` and `apitester.runTestCases(..)`