mock-cmdr - npm Package Compare versions

Comparing version 1.0.0 to 1.0.1

lib/index.js

@@ -113,3 +113,3 @@ const Session = require('./session');
    * Load all "find" and "stub" mocking commands by searching recursively
-   * within baseDir.
+   * within cmdDir.
    *
@@ -132,3 +132,3 @@ * The discovered commands will be passed to `defineCmd()` using the camel
    *    //
-   *    // [baseDir]
+   *    // [cmdDir]
    *    //   |
@@ -154,3 +154,3 @@ *    //   |- stub
    *    //
-   *    // [baseDir]
+   *    // [cmdDir]
    *    //   |
@@ -173,4 +173,4 @@ *    //   |- my-service
    */
-  loadCmds(baseDir) {
-    cmdRegistry.loadCmds(baseDir);
+  loadCmds(cmdDir) {
+    cmdRegistry.loadCmds(cmdDir);
     return this;
@@ -177,0 +177,0 @@ },

package.json

 {
   "name": "mock-cmdr",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Wiremock Client",
@@ -5,0 +5,0 @@ "main": "lib/index.js",

README.md

@@ -6,38 +6,200 @@ # Mock Commander
 
-### Run Unit Tests
+Wiremock client for Node JS which promotes separation of dynamic mocking
+commands from test code logic.
 
+
+## Installation
+
 ```
-yarn install
-yarn test
+npm install mock-cmdr
 ```
 
 
-### Run Cucumber Tests
+## Usage
 
+Mock Commander can be simply used as a Wiremock rest API client:
+
 ```
-yarn install
-docker-compose run cucumber yarn cucumber
+const mockCmdr = require('mock-cmdr');
+mockCmdr.init({ baseUrl: 'http://wiremock' });
+mockCmdr.createMapping({
+  request: {
+    method: 'GET',
+    urlPath: '/user/1',
+  },
+  response: {
+    jsonBody: {
+      id: 1
+    }
+  },
+});
 ```
 
+However, Mock Commander's real utility comes from defining templated Wiremock
+commands. If the mapping definintion above is moved into
+`${__dirname}/mock/stub/get-user-by-id.js` then the same create mapping call
+can be made by:
 
-### Inspect Test Traffic with Mitmweb
+```
+const user = { id: 1 };
+await mockCmdr.stub.getUserById(user);
+```
 
-Start Mitmweb:
+Commands are loaded by providing the `cmdDir` option to `mockCmdr.init()`:
 
 ```
-docker-compose \
-  -f ./docker-compose.yml \
-  -f ./docker-compose.proxy.yml \
-  up --detach
+const path = require('path');
+const mockCmdr = require('mock-cmdr');
+mockCmdr.init({
+  baseUrl: wiremockBaseUrl,
+  cmdDir: path.resolve(__dirname, 'mock'),
+});
 ```
 
-Run tests:
+See the [Mock Commander Cucumber Test Suite][] for a full example demonstrating
+how to define and use templated Wiremock commands with Cucumber.
 
+
+### Command Dir Layout
+
+The following example demonstrates the layout of a command dir:
+
 ```
-docker-compose \
-  -f ./docker-compose.yml \
-  -f ./docker-compose.proxy.yml \
-  run cucumber yarn cucumber
+[cmdDir]
+  |- stub
+  |  |- user
+  |     |- create.js
+  |     |- get-by-id.js
+  |
+  |- find
+     |- user
+        |- create-by-email.js
 ```
 
-Browse to Mitmweb at http://localhost:8081/.
+The resulting commands after calling `mockCmdr.init({ cmdDir })` will be:
+
+```
+mockCmdr.stub.user.create()
+mockCmdr.stub.user.getById()
+mockCmdr.find.user.createByEmail()
+```
+
+### Example Stub Command
+
+```
+/**
+ * @returns {WiremockStubMapping}
+ */
+module.exports = function(user) {
+  return {
+    request: {
+      method: 'GET',
+      urlPath: `/user/${user.id}`,
+    },
+    response: {
+      jsonBody: user.toApiModel(),
+    },
+  };
+};
+```
+
+### Example Find Command
+
+```
+/**
+ * @returns {WiremockRequestCriteria}
+ */
+module.exports = function(user) {
+  return {
+    method: 'GET',
+    urlPath: `/user/${user.id}`,
+  };
+};
+```
+
+## API Summary
+
+### mock-cmdr module
+
+#### .init(options)
+
+Initialize the Mock Commander session. If `cmdDir` is specified then
+`loadCmds()` will also be called.
+
+**options:**
+* **baseUrl** (string) - the mock server base URL, eg: `http://wiremock:8080`.
+* **cmdDir** (string) - the dir to load commands from.
+
+#### .defineCmd(command)
+
+Define a templated mocking command that will be available via
+`mockCmdr.{type}.{path}` or `mockCmdr.{type}.{name}`. When the command is
+invoked then `createMapping()` or `findRequests()` will be called with the
+output of the command's template function.
+
+**command:**
+* **type** (string) - `"stub"` or `"find"`.
+* **path** (string[]) - the path the command will be available at within
+  `mockCmdr.stub` or `mockCmdr.find`.
+* **name** (string) - shorthand for `{ path: [ name ] }`
+* **template** (function) - A function that returns either a "find requests" criteria or a
+  "stub mapping" definition.
+
+
+#### .loadCmds(dir)
+
+Load all "find" and "stub" mocking commands by searching recursively
+within baseDir.
+
+The discovered commands will be passed to `defineCmd()` using the camel
+cased file names as the command path. Modules found within a "find"
+directory are treated as "find" commands and modules found within a
+"stub" directory are treated as "stub" commands. Modules not within a
+"find" or "stub" directory are ignored.
+
+Any intermediate directories other than "find" and "stub" will be
+treated as namespaces. Namespaces can be arbitrarily deep and are also
+camel cased. The "find" and "stub" dirs are excluded from the namespace
+and need not appear at the top level allowing related commands to be
+grouped appropriately.
+
+
+#### .createMapping(mapping)
+
+*async*
+
+Call the [Wiremock Stub Mapping API][].
+
+
+#### .findRequests(criteria)
+
+*async*
+
+Call the [Wiremock Find Requests API][].
+
+#### .stub
+
+Access to "stub" commands registered via `mockCmdr.defineCmd()`.
+
+
+#### .find
+
+Access to "find" commands registered via `mockCmdr.defineCmd()`.
+
+
+#### .cleanUp()
+
+*async*
+
+Remove stub mappings from the Wiremock server that have been created by the
+current session.
+
+
+Legal
+-----
+
+Copyright 2020 Nathan Jones. Licensed under the Apache License, Version 2.0.
+
+[Mock Commander Cucumber Test Suite]: https://github.com/ncjones/mock-cmdr/tree/master/features/
+[Wiremock Stub Mapping API]: http://wiremock.org/docs/api/#tag/Stub-Mappings/paths/~1__admin~1mappings/post
+[Wiremock Find Requests API]: http://wiremock.org/docs/api/#tag/Requests/paths/~1__admin~1requests~1find/post

No alert changes

Improved metrics

Total package byte prevSize

42111

increased by12.59%

Number of package files

50

increased by2.04%

Number of lines in readme file

205

increased by376.74%

No dependency changes