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

@9paradox/apitester

v0.1.9

Published

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

95

Readme

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

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

| Parameter | Type | Required | Description | | :------------- | :-------------------------------------- | :------- | :--------------------------------------------------------------------------------------------------------------- | | title | string | no | Title for the test case. | | dataFilePath | string | no | File path for JSON data key-value file. | | steps | StepOptions[] | no | Add steps while creating testcase. Check type reference. | | logPath | string | no | Logging folder path. | | logEachStep | boolean | no | Used to enable logging each step. | | callback | (data: CallbackData) => Promise<void> | no | Callback function called before and after each step. |

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.

| Action (ActionName) | Input Type | Return Type | Description | | :------------------ | :----------------------- | :---------- | :--------------------------------------------------------------------------------------------- | | get | GetOptions | TestCase | Perform GET http request. | | post | PostOptions | TestCase | Perform POST http request. | | axios | AxiosOptions | TestCase | Perform http request based on AxiosRequestConfig. | | inputData | any | TestCase | Holds input data for next step. | | pickData | string | TestCase | Perform json query to pick data from last step. | | buildData | BuildDataOptions | TestCase | Build and merge your data from different steps using json query. | | formatData | string | TestCase | Render string template based on input data from last step using Eta.js. | | formatTemplate | FormatTemplateOptions | TestCase | Render template file based on input data from last step using Eta.js. | | pickAndVerify | PickAndVerifyOptions | TestCase | Perform json query to pick data from last step and do a test assert. | | verify | VerifyOptions | TestCase | To assert data from last step. | | verifyTimeTaken | VerifyTimeTakenOptions | TestCase | To assert time taken for last step. | | pickStep | number | TestCase | To pick output data from specific step. Also supports negative index from current step. | | addStep | StepOptions | TestCase | Add a steps from JSON object. | | customFn | CustomFnOptions | TestCase | Run custom function as a step. | | customFnFrom | CustomFnFromOptions | TestCase | Run custom function from a javascript file as a step. | | log | - | TestCase | Last steps will be logged to a file. | | getStep | number | Step | Returns the specific step with its input and output data. |

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.

| Parameter | Type | Required | Description | | :----------- | :------------------ | :------- | :---------------------------------------------------------- | | type | before or after | yes | Used to identify if the callback is called before or after. | | step | Step | yes | Current step. | | stepResult | StepResult | no | Step success result updated in type 'after'. |

TestCaseCallbackData

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

| Parameter | Type | Required | Description | | :--------------- | :------------------ | :------- | :---------------------------------------------------------- | | type | before or after | yes | Used to identify if the callback is called before or after. | | filePath | string | yes | Current testcase file path. | | testCaseResult | TestCaseResult | no | Testcase success result updated in type 'after'. |

GetOptions

Create GetOptions using one of the following type.

| Type | Description | | :------------------- | :----------------------------------------------------------------------- | | string | String URL. | | AxiosRequestConfig | Axios Request config object. | | undefined | To pick string URL from last step. |

PostOptions

Create PostOptions using one of the following type.

| Type | Description | | :------------------- | :----------------------------------------------------------------------- | | SimplePostConfig | Object with string url and any data. | | AxiosRequestConfig | Axios Request config object. | | undefined | To pick SimplePostConfig from last step. |

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

| Parameter | Type | Required | Description | | :-------- | :------- | :------- | :------------------------------------ | | step | number | yes | Step number to perform json query on. | | query | string | yes | Json query. | | name | string | yes | Field name to store value into. |

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.

| Parameter | Type | Required | Description | | :--------- | :------- | :------- | :------------------------- | | query | string | yes | Query string to pick data. | | expected | any | yes | Expected data. | | toBe | ToBe | no | Comparison type. |

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.

| Parameter | Type | Required | Description | | :--------- | :---------- | :------- | :---------------------------------------------------------------------------- | | expected | number | yes | Expected time. | | format | ms or s | yes | Compare expected time against ms (milliseconds) or s (seconds) of actual time | | toBe | ToBe | yes | Comparison type. |

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.

| Parameter | Type | Required | Description | | :------------- | :--------- | :------- | :---------------------------------------------------- | | stepType | StepType | yes | Type of step. | | filePath | string | yes | Filepath of the javascript file. | | functionName | string | yes | Name of the function which is exported from the file. |

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.

| Values | Description | | :------------- | :--------------------------------------------------------------------- | | Action | To denote the step will perform some testcase related action. | | Verification | To denote the step will perform verification or assertion on action/s. | | Logging | To denote the step will perform logging action/s. |

VerificationResult

Return type for verification step.

| Parameter | Type | Required | Description | | :----------- | :-------- | :------- | :---------------------------------------------- | | verified | boolean | yes | To denote if the step has passed the assertion. | | actualData | any | yes | Actual data from the step used for assertion. | | message | string | no | Any message or verification error message. |

QueryLang

Enum to identify which json query library to use.

| Query string starts with | Values | Description | | :----------------------- | :--------- | :---------------------------------------------------------------------------------------------------------------------------------------- | | @jmespath | jmespath | To denote the query will be performed using jmespath. | | @jsonata | jsonata | To denote the query will be performed using jsonata. Note: jsonata query are work in progress in current release. |

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.

| Parameter | Type | Required | Description | | :--------------------------------- | :-------- | :------- | :--------------------------------------------------------------------------------------------- | | success | boolean | yes | Denotes if the testcase is successful. | | totalSteps | number | yes | Total number of steps. | | executedSteps | number | yes | Total number of steps are executed. | | lastExecutedStep | number | yes | Step number of last step that was executed. | | totalVerificationSteps | number | yes | Total number of verification type of steps . | | executedVerificationSteps | number | yes | Total number of verification type of steps that were executed. | | totalSuccessfulVerificationSteps | number | yes | Total number of verification type of steps that were executed and were successful. | | lastVerificationStep | number | yes | Step number of last verification type of step that was executed. | | steps | Step[] | yes | List of all steps in the testcase. | | error | Error | no | Error object containing error details. |

MultiTestCaseResult

Structure of multi testcase execution.

| Parameter | Type | Required | Description | | :---------------- | :----------------- | :------- | :------------------------------------------ | | success | boolean | yes | Denotes if all the testcase are successful. | | failedTestCases | number | yes | Total number of failed testcases. | | testCaseResults | TestCaseResult[] | yes | List of all testcase result. | | error | Error | no | Error object containing error details. |

Error

Structure of testcase error.

| Parameter | Type | Required | Description | | :---------- | :--------------------- | :------- | :----------------------------------------------------- | | title | string | yes | Error title with step number where the error occurred. | | message | string | no | More detail description of the error. | | exception | string | no | Exception in Json stringified form. | | type | error or exception | no | Denotes the type of error. |

Roadmap

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

License

MIT