README.md

What is it?

REST-EZ is a declarative, spec based test framework for REST & GraphQL APIs.

You can test APIs without writing code, but can also write code when needed. REST-EZ reads API test specs from YAML files and can runs them serially or in parallel.

Test reports can be generated in several formats including HTML and JSON.

How does it work?

Build a test suite by providing a set of request and response validation specification in a YAML file.

Each suite can have one or more specs. REST-EZ builds the request, sends it to server and validates response as per the specification.

Choose to validate any or all of following

• Status code
• Headers
• Cookies
• Response JSON body
• Response JSON schema

or Provide a custom Javascript function to validate the response

Read the docs to learn more

Links

• Documentation
• Issue Tracker

Getting Started

To run just-api, you will need Node.js v10.x.x or newer.

Installation

$ npm install rest-ez --save-dev

Following is a simple example showing usage of REST-EZ.

$ mkdir specs
$ vim specs/starwars-service.yml

Write following suite in your editor

meta:
  name: Star Wars suite
configuration:
  scheme: https
  host: swapi.co
  base_path: /api
specs:
  - name: get Luke Skywalker info
    request:
      path: /people/1/
      method: get
    response:
      status_code: 200
      headers:
        - name: content-type
          value: !!js/regexp application/json
      json_data:
        - path: $.name
          value: Luke Skywalker

Back in the terminal

$ ./node_modules/.bin/just-api

   ✓ get Luke Skywalker info (1216ms)

  Done: specs/starwars-service.yml (Passed)

0 skipped, 0 failed, 1 passed (1 tests)
0 skipped, 0 failed, 1 passed (1 suites)
Duration: 1.3s

Testing GraphQL APIs

Following example tests a GraphQL API that returns Person info for a given name.

Create a YAML suite and run just-api.

meta:
  name: GraphQL Starwars service
configuration:
  host: swapi.graph.cool
  scheme: https
specs:
  - name: Get Details of a character
    request:
      method: post
      headers:
        - name: content-type
          value: application/json
      payload:
        body:
          type: json
          content:
            query: >
             {
              Person(name: "Luke Skywalker") {
                name,
                id,
                gender
               }
              }
            variables: null
            operationName: null
    response:
      status_code: 200
      json_data:
        - path: $.data.Person.name
          value: Luke Skywalker

A chained request flow with hook and custom validation

When you need to test complex chained API flows, run dependencies in hooks to fetch pre-requisite data and pass it to actual test.

Following example shows how to run dependencies using a hook, get data and validating response with a custom validator function.

meta:
  name: Starwars suite
configuration:
  scheme: https
  host: swapi.co
  base_path: /api
specs:
  - name: get R2-D2 info
    request:
      path: /people/3/
      method: get
    response:
      status_code: 200
      json_data:
        - path: $.name
          value: R2-D2

  - name: search R2-D2 info
    before_test:
      run_type: inline
      inline:
        function: !js/asyncFunction >
          async function() {
            var response = await this.runSpec('get R2-D2 info');
            var jsonData = JSON.parse(response.body);
            this.test.query_params = { name:  jsonData.name };
          }
    request:
      path: /people
      method: get
    response:
      status_code: 200
      custom_validator:
        run_type: inline
        inline:
          function: !!js/function >
            function() {
              var jsonData = JSON.parse(this.response.body);
              var r2d2 = jsonData.results.find(result => result.name === 'R2-D2');
              if (!r2d2)
                throw new Error('R2-D2 not returned in search results');
            }

Note: You can also place custom JS functions in a module and specify the function name, module path in YAML to import.

More advanced stuff can be done with REST-EZ. Documentation says it all. Take a look at REST-EZ Website for detailed documentation.

Maintainers

Matthew J. Martin

License

MIT-licensed

Documentation

• Installation
• Getting Started
• Basic Concepts
• Requests
  • Headers
  • Cookies
  • Query Parameters
  • Path Parameters
  • Request Body
    • JSON Body
    • Binary Data
    • URL Encoded Form Data
    • URL Encoded Form Data
    • Multi-Part Form Data
  • File Uploads
  • Additional Options
• Response Validation
  • Status Code Validation
  • Cookie Validation
  • Header Validation
  • Body Validation
    • JSON Path
    • JSON Schema Inline
    • JSON Schema File
    • Swagger / Open API
• Lifecycle Hooks
  • Hook Types
    • JS Inline Functions
    • JS Async Inline Functions
    • JS Modules
  • List of Hooks
    • before_all
    • after_all
    • before_each
    • after_each
    • before_test
    • after_test
  • Hook Context
    • Suite Context
    • Test Context
    • Response Context
• Reusing Specs & DRY
  • Looping
  • Yaml Anchors
  • Run Existing Spec
• Command Line Interface (CLI)
  • Debugging
  • Running Suites in Parallel
  • Reporters
  • Options

Acknowledgements

👏👏👏 Enormous thanks to Kiran Mandadi,

Original creator of rest-ez upon which this project is based (forked).

👏👏👏 Thanks to corporate sponsors

• Blossom Finance ethical investments in micro businesses
• LaunchGood crowdfunding incredible Muslims

Roadmap & TODO

• ✅ Full support for de-referencing schema $refs
• ✅ Allow specifying node within a schema file using JSON pointer
• ✅ ~~Pass arguments to inline or module-based functions to allow creater re-use~~~
• Documentation improvements
  • ✅ Upgrade markdown static site generator (something without python dependency)
  • ✅ Example function with arguments usage
  • ✅ JSON schema validation de-referencing schema $refs
  • ✅ Specify node within a schema file using JSON path
  • Examples directly using files within node_modules
• Reporter improvements & enhancements
  • ✅ TAP (test anything protocol) support
  • JSON output to console or file option
  • Clearly document reporter options in CLI
• Replace commander with yargs for improved CLI docs & defaults
• Example of how to use faker.js using reusable function
• Code Quality - add linter/hinter/prettier or whatever spec is used
• Update to use ECMA6 modules & deprecate Babel (possibly TypeScript?)

Contributing

Running Tests

1. Install deps npm install
2. Install & run test API npm run test-api
3. (In a new window) run tests npm test

Releasing

npm run release

This command should automatically:

1. Determine next release version from conventional commit history
2. Update the CHANGELOG.md
3. Rev package.json, commit, & tag, etc.
4. Publish to npm
5. Create a Github release

Testing

Tests have two components

• JS chai/mocha tests about the sample suite/specs in test/cli/[suite].spec.js
• REST-EZ suites/specs in test/cli/src/suites/[suite].spec.yaml

You will likely need to create/modify both a REST-EZ suites/specs` and also the accompanying JS chai/mocha tests to add test coverage.

Features

Mostly here for SEO purposes:

• Runs test suites in parallel/serial mode
• Supports all widely used HTTP methods
• Supports x-www-form-urlencoded requests, Multipart requests, File uploads
• Built-in Response Validation Constructs (Headers, Cookies, Status code, JSON body, JSON schema)
• Custom Response validator functions
• Supports running custom inline or module javascript sync/async functions
• Supports Hooks (Before All, After All, Before Each, After Each, Before Test, After Test)
• Custom suite configuration
• Chained Request flows
• Define/override Request path, query params, path params, headers, body at runtime
• Suite and test context for reuse
• Supports importing specs from one or more test suites
• Intrasuite and Intersuite spec dependencies
• Reusing test specification
• Retry failed tests
• Looping: Generate 'n' number of tests with a list
• Built-in HTML, JSON reporters
• Can generate reports in multiple formats for the same run
• Logging HTTP request/response data for failed tests
• Proper error reporting
• Can run tests matching with a given pattern/string
• Skipping tests with specification
• Disable or Enable redirections
• Reports test duration
• Allows user to plug-in custom reporters