Nonviolent Pigeon Manifestation

    moxx

    0.4.2 • Public • Published

    moxx

    NPM version License Travis CI Coverage Status Dependencies

    moxx is a tool to easily mock your external APIs. No more failed tests because of fragile dependencies.

    NPM

    Features

    Disclaimer

    This project is heavily inspired by wiremock written in java.

    Requirements

    • Node.js 6+
    • npm 3+

    Installation

    npm i -g moxx

    Usage

    moxx
    

    Options

    Option Default Description
    -h, --help Output usage information
    -V, --version Output the version number
    -p, --port <port> 5000 The port number for the server to listen on
    -d, --dir <directory> . The root config/mapping/files directory
    -w --watch false Watch for changes
    -r, --record false Records proxy requests/responses
    -x, --proxy <proxy> Act as a proxy
    --no-color false Disable color
    -l, --loglevel info Sets logger log level

    Configuration

    moxx requires two directories, mappings and files to run, if they don't exist, it will create them. Those directories should be available under the dir option (default to .).

    The mappings directory contains yaml files which define the mapping between incoming requests parameters (method, url, query, headers…) and responses, the files directory contains files to be used as response body.

    The mappings files are loaded in memory whereas the files are loaded when required and not cached, it means if you modify a mapping file, the change you make won't be available immediately, if you want this you should consider using the watch option. If you change the content of a file or add one in the files directory, it will be available without restart or requiring the watch option.

    Mapping file

    The typical structure of a mapping file is:

    get_users: # must be unique among all mappings 
      request: # rules for matching 
        method: GET
        url:    /users
      response: # response to send on match 
        status: 200
        body:   hello world

    Please, see request matching for further details on request configuration.

    The response configuration accepts several keys:

    get_users:
      # ... 
      response:
        status: 200
        headers:
          Content-Type: application/json
        # you cannot use both body and bodyFile   
        body:     hello world
        bodyFile: hello-world.txt

    Watching changes on mappings

    moxx --watch

    Request matching system

    moxx provides a powerful request matching system.

    Matching http method

    # match GET method 
    method_get:
      request:
        method: GET
        
    # match all methods 
    method_any:
      request:
        method: '*'

    Matching url

    Internally, moxx uses minimatch.

    # match /users 
    users:
      request:
        url: /users
     
    # match /users/2 
    user_2:
      request:
        url: /users/*
        
    # match /users/2/profile 
    user_2_profile:
      request:
        url: /users/**    

    Matching query

    Unlike the method and url matchers, query matching provides more versatile matchers to ease mock definition.

    # exists 
    get_user_with_id:
      request:
        query:
          id:
            exists: true
     
    # equals         
    get_user_with_id_2:
      request:
        query:
          id:
            equals: 2
          # alternative form 
          id: 2 # defaults to equals matcher 
            
    # includes         
    get_user_with_username_including_plouc:
      request:
        query:
          username:
            includes: plouc

    Matching headers

    Unlike the method and url matchers, headers matching provides more versatile matchers to ease mock definition.

    # exists 
    get_user_with_x-id:
      request:
        headers:
          x-id:
            exists: true
     
    # equals         
    get_user_with_x-id_2:
      request:
        headers:
          x-id:
            equals: 2
          # alternative form 
          x-id: 2 # defaults to equals matcher 
            
    # includes         
    get_user_with_x-username_including_plouc:
      request:
        headers:
          x-username:
            includes: plouc

    Matching files

    moxx is able to check posted files, testing against file fieldname/filename/checksum.

    Matching file fieldname

    Checks a request contains a file which fieldname equals/includes given value.

    # curl -X POST -F "myfile=@$(pwd)/README.md" http://localhost:5000 
    one_file_with_fieldname_myfile:
      request:
        method: POST
        files:
          count: 1
          files:
            fieldname: myfile
      response:
         status: 200
         body:   one_file_with_fieldname_myfile
         
    # curl -X POST -F "includedfile=@$(pwd)/README.md" http://localhost:5000 
    one_file_with_fieldname_includes:
      request:
        method: POST
        files:
          count: 1
          files:
            fieldname:
                includes: included
      response:
         status: 200
         body:   one_file_with_fieldname_includes     

    Matching file filename

    Checks a request contains a file which filename equals/includes given value.

    # curl -X POST -F "myfile=@$(pwd)/package.json" http://localhost:5000 
    one_file_with_filename_packagejson:
      request:
        method: POST
        files:
          count: 1
          files:
            fieldname: myfile
              filename:  package.json
      response:
        status: 200
        body:   one_file_with_filename_packagejson
        
    # curl -X POST -F "myfile=@$(pwd)/LICENSE.md" http://localhost:5000 
    one_file_with_filename_includes:
      request:
        method: POST
        files:
          count: 1
          files:
            fieldname: myfile
              filename:
                includes: LICENSE
      response:
        status: 200
        body:   one_file_with_filename_includes    

    Matching file checksum

    Checks a request contains a file which checksum equals given value (md5 on file content).

    # curl -X POST -F "file=@$(pwd)/test/fixtures/files/plouc.png" http://localhost:5000 
    one_file_with_checksum:
      request:
        method: POST
        files:
          count: 1
          files:
            fieldname: file
              checksum:  049d9c8330df21e891e214681ec02b8f
      response:
        status: 200
        body:   one_file_with_checksum

    Scoring

    moxx implements a scoring system to match requests, each rule you define increment the score of a mapping, in the end the response whose request has the highest score will be sent.

    # this entry will be eligible but will always have a score of 0 because no rule is defined 
    default:
      request:  {}
      response:
        status: 200
        body:   moxx
     
    # this entry will have a score of 1 if the incoming request is a GET request     
    get_method:
      request:
        method: GET
      response:
        status: 200
        body:   moxx GET request
        
    # this entry will have a score of 2 if the incoming request is a GET request and the url is /users 
    get_users:
      request:
        method: GET
        url:    /users
      response:
        status: 200
        body:   moxx GET users request

    given this mapping:

    • HEAD / will use default response (score: 0)
    • GET / will use get_method response (score: 1)
    • GET /users will use get_users response (score: 2)

    Proxying

    moxx --proxy https://api.github.com
    

    Recording

    moxx --proxy https://api.github.com --record
    

    Install

    npm i moxx

    DownloadsWeekly Downloads

    0

    Version

    0.4.2

    License

    MIT

    Last publish

    Collaborators

    • plouc