@9paradox/apitester v0.1.9

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.

Table of Contents

• Installation
• Usage
• Type reference

Installation

Install into an new or existing javascript/typescript project.

npm i @9paradox/apitester

Usage

1. 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.
2. The testcase can perform multiple steps/actions.
3. Each step/action requires input data. Some of the steps can use output data from previous step as input.
4. 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.

apitester-creator

Now easily create testcases with the online drag-and-drop tool - 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.

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.

QueryData

FormatTemplateOptions

Create FormatTemplateOptions using one of the following type.

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.

VerifyTimeTakenOptions

Verify time taken by last step.

CustomFnOptions

User provided function to run as a step.

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.

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