@blossomfinance/rest-ez

    1.5.4 • Public • Published

    REST-EZ

    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

    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

    Acknowledgements

    👏👏👏 Enormous thanks to Kiran Mandadi,

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

    👏👏👏 Thanks to corporate sponsors

    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
    • [ ] Example of how to use faker.js using reusable function
    • [ ] Code Quality - add linter/hinter/prettier or whatever spec is used

    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

    Install

    npm i @blossomfinance/rest-ez

    DownloadsWeekly Downloads

    7

    Version

    1.5.4

    License

    MIT

    Unpacked Size

    175 kB

    Total Files

    26

    Last publish

    Collaborators

    • matmar10