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

elbow

v1.1.1

Published

An easy way to test REST API responses with Mocha

Downloads

25

Readme

elbow

An easy way to test REST API responses with Mocha

Version Supported Node.js Versions Build Status Coverage Status Dependency Status

elbow = mocha + superagent + ajv

what makes it easy?

  1. Utilizes the power of JSON Schema (see also).
  2. You do not need to write code for interacting with the API.
  3. Your schemas define what endpoints they are tested against, along with parameters, such as request headers and body.
  4. Offers a gentle learning curve.

usage:

A sample test script:

const elbow = require("elbow");

describe("testing Http Responses", function() {
  elbow.run(it, "http://localhost:9090/", `${__dirname}/../schema`, {
    timeout: 5000,
  });
});

See a sample schema.

See a sample test output.

installation:

⇒ npm install elbow --save-dev

API:

const elbow = require("elbow");

elbow.run(it, baseUrl, schemaDir [, options])

Runs your tests.

  • it (Function): it provided by Mocha.
  • baseUrl (String): base URL of the server. This is used to resolve the relative urls (endpoints).
  • schemaDir (String): path to the directory holding your schemas.
  • options (Object): test configurations
    • options.timeout (Integer): test-specific timeout
    • options.label (Function):
      • returns a custom it label
      • signature: function(method, schema)
    • options.headers (Object): headers sent on each request. Merged with headers found in schema.
    • options.query (Object): query parameters sent on each request. Merged with query found in schema.
    • options.body (Object): body parameters sent on each request. Merged with body found in schema.
    • options.vars (Object): variables used in variable expansions.
    • options.before (Function): before by Mocha; Makes elbow look for setup schemas in the setup directory in schemaDir. These schemas are run before any test cases.
    • options.beforeBaseUrl (String): base URL used in setup. Otherwise baseUrl is used.
    • options.extensions (String[]): extensions of schema files to be used. Defaults to ["json"]. See using other file formats.

elbow.schemas(schemaDir, callback)

Loads your schemas.

  • schemaDir (String): path to the directory holding your schemas.
  • callback (Function):
    • signature: callback(err, schemas)
    • schemas (Array): array holding your schemas

schemas:

Schemas, as defined in its specification, are valid JSON documents.

All the schemas should be placed in a single directory. They should have the extension .json.

A sample schema file would look like:

{
  "$schema": "http://json-schema.org/schema#",

  "endpoint": "/test/endpoint",
  "description": "test endpoint",
  "methods": ["post"],
  "params": {
    "key": "value"
  },
  "headers": {
    "Authorization": "${OAUTH_TOKEN}"
  },
  "query": {
    "key": "value"
  },
  "body": {
    "key": "value"
  },

  "status": 200,
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    }
  },
  "required": ["ok"],

  "export": {
    "var_name": "ok"
  }
}

Required key-value pairs include:

  • endpoint (String): endpoint to test. This will be resolved to an absolute url using the base url. e.g. /endpoint
  • description (String): describes the significance of the http response. e.g. "creating a new resource object"
  • methods (Array): all the http methods to use to test the endpoint
    • possible values: "get", "post", "put", "delete"

Optional key-value pairs include:

  • headers (Object): headers to send in request
  • query (Object): query parameters to send in request
  • body (Object): body to send in request. Only applied if method is "post" or "put"
  • status (Number): response status code. e.g. 201
  • export (Object): variables to be exported. See exporting variables
  • params (Object): DEPRECATED: Use headers, query or body instead!
    • parameters to pass to endpoint. e.g. { "query": "name" }

variable expansion:

The endpoint, headers, query and body parameters can contain variables, in the form, ${VARIABLE_NAME}, that will be expanded as necessary. The value is determined from options.vars (see above) or from the process environment. If the value could not be determined, the variable is not expanded i.e. is ignored.

variable exports:

The export parameter is used to export variables from the test case making them available for any following test cases. The key-value pairs under export are such that: they key defines the name of the variable and the value defines the path in the response body to the property to be used. For example, if response body was:

{
  "setup": {
    "token": "am.a.token"
  }
}

and the export parameter was:

{
  "export": {
    "setup_token": "setup.token"
  }
}

would export the variable ${setup_token} with value "am.a.token" at path setup.token. Any following schemas [sic: read test cases] can access ${setup_token} and it'll resolve successfully. See lodash.get/lodash.set.

using other file formats:

You can use other file formats such as JSON5 and YAML. Before using describe() you need to install the require extension for your file format. For example,

const fs = require("fs");
const yaml = require("js-yaml");
const elbow = require("elbow");

require.extensions[".yml"] = function(mod, filename) {
  mod.exports = yaml.safeLoad(fs.readFileSync(filename, "utf8"));
};

describe("using yaml", function() {
  elbow.run(it, "http://localhost:8080", path.join(__dirname, "example"), {
    extensions: ["yml"],
  });
});

You can now write your schema files in YAML e.g. example.yml.


The rest of the document will be used as is in validation.

The test cases are created in the order of:

  1. filename of the schema files. e.g. 01-get.json is used before 02-get.json
  2. indices of "methods" in the schema. e.g. with ["post", "get"], "post" is used before "get"

This allows you to use a sequence in your tests, without having to use any beforeEach, any code, etc...

test output:

Sample Test Output:

  ✓ GET /params (testing the sending of params) [/home/gocho/Repos/GochoMugo/github/elbow/test/schema/params.json] (60ms)
  ✓ POST /params (testing the sending of params) [/home/gocho/Repos/GochoMugo/github/elbow/test/schema/params.json]
  ✓ PUT /params (testing the sending of params) [/home/gocho/Repos/GochoMugo/github/elbow/test/schema/params.json]
  ✓ DELETE /params (testing the sending of params) [/home/gocho/Repos/GochoMugo/github/elbow/test/schema/params.json]
  ✓ GET /simple (testing the response body only) [/home/gocho/Repos/GochoMugo/github/elbow/test/schema/simple.json]
  ✓ POST /simple (testing the response body only) [/home/gocho/Repos/GochoMugo/github/elbow/test/schema/simple.json]
  ✓ PUT /simple (testing the response body only) [/home/gocho/Repos/GochoMugo/github/elbow/test/schema/simple.json]
  ✓ DELETE /simple (testing the response body only) [/home/gocho/Repos/GochoMugo/github/elbow/test/schema/simple.json]

The method and endpoint is shown for each test case. The description of the schema is shown between ( and ). The absolute filepath of the schema file used in the test case is shown between [ and ].

terminal usage:

Elbow is also available from your terminal.

If installed globally, the command elbow will be readily available. Otherwise, elbow will be available at ./node_modules/.bin/elbow.

listing your schemas:

To list your schemas with the respective descriptions.

⇒ elbow --list [absolutePathToSchemaDir]

notes:

  1. Synchronous file operations are used internally to ensure test cases are executed in correct order by mocha.

license:

The MIT License (MIT)

Copyright (c) 2015-2017 GochoMugo [email protected]