Add test mode (#225)

* Remove key- and pubkey- prefix from documentation. Fixes #208.

* Add test mode. Fixes #160

* update test mode docs

* add spy tests for test mode

README.md

@@ -28,7 +28,7 @@ of the `error` object passed in the callback.
 See the `/docs` folder for detailed documentation. For full usage examples see the `/test` folder.
 
 ```js
-var api_key = 'key-XXXXXXXXXXXXXXXXXXXXXXX';
+var api_key = 'XXXXXXXXXXXXXXXXXXXXXXX';
 var domain = 'www.mydomain.com';
 var mailgun = require('mailgun-js')({apiKey: api_key, domain: domain});
 
@@ -104,6 +104,8 @@ list.members('bob@gmail.com').delete(function (err, data) {
 That is, we will try an operation only once with no retries on error. You can also use a config
 object compatible with the `async` library for more control as to how the retries take place.
 See docs [here](https://caolan.github.io/async/docs.html#retry)
+* `testMode` - turn test mode on. If test mode is on, no requests are made, rather the request options and data is logged
+* `testModeLogger` - custom test mode logging function
 
 
 #### Attachments
@@ -423,12 +425,90 @@ mailgun.parse([ 'test@mail.com', 'test2@mail.com' ], function (err, body) {
 });
 ```
 
+## Debug logging
+
+[debug](https://npmjs.com/package/debug) package is used for debug logging.
+
+```sh
+DEBUG=mailgun-js node app.js
+```
+
+## Test mode
+
+Test mode can be turned on using `testMode` option. When on, no requests are actually sent to Mailgun, rather we log the request options and applicable payload and form data. By default we log to `console.log`, unless `DEBUG` is turned on, in which case we use debug logging.
+
+```js
+mailgun = require('mailgun-js')({ apiKey: api_key, domain: domain, testMode: true })
+
+const data = {
+  from: 'mailgunjs+test1@gmail.com',
+  to: 'mailgunjstest+recv1@gmail.com',
+  subject: 'Test email subject',
+  text: 'Test email text'
+};
+
+mailgun.messages().send(data, function (error, body) {
+  console.log(body);
+});
+```
+
+```
+options: { hostname: 'api.mailgun.net',
+  port: 443,
+  protocol: 'https:',
+  path: '/v3/sandbox12345.mailgun.org/messages',
+  method: 'POST',
+  headers:
+   { 'Content-Type': 'application/x-www-form-urlencoded',
+     'Content-Length': 127 },
+  auth: 'api:key-0e8pwgtt5ylx0m94xwuzqys2-o0x4-77',
+  agent: false,
+  timeout: undefined }
+payload: 'to=mailgunjs%2Btest1%40gmail.com&from=mailgunjstest%2Brecv1%40gmail.com&subject=Test%20email%20subject&text=Test%20email%20text'
+form: undefined
+undefined
+```
+
+Note that in test mode no error or body are returned as a result.
+
+The logging can be customized using `testModeLogger` option which is a function to perform custom logging.
+
+```js
+const logger = (httpOptions, payload, form) => {
+  const { method, path } = httpOptions
+  const hasPayload = !!payload
+  const hasForm = !!form
+
+  console.log(`%s %s payload: %s form: %s`, method, path, hasPayload, hasForm)
+}
+
+mailgun = require('mailgun-js')({ apiKey: api_key, domain: domain, testMode: true, testModeLogger: logger })
+
+const data = {
+  from: 'mailgunjs+test1@gmail.com',
+  to: 'mailgunjstest+recv1@gmail.com',
+  subject: 'Test email subject',
+  text: 'Test email text'
+};
+
+mailgun.messages().send(data, function (error, body) {
+  console.log(body);
+});
+```
+
+Sample output:
+
+```
+POST /v3/sandbox12345.mailgun.org/messages payload: true form: false
+undefined
+```
+
 ## Tests
 
 To run the test suite you must first have a Mailgun account with a domain setup. Then create a file named _./test/data/auth.json_, which contains your credentials as JSON, for example:
 
 ```json
-{ "api_key": "key-XXXXXXXXXXXXXXXXXXXXXXX", "public_api_key": "pubkey-XXXXXXXXXXXXXXXXXXXXXXX", "domain": "mydomain.mailgun.org" }
+{ "api_key": "XXXXXXXXXXXXXXXXXXXXXXX", "public_api_key": "XXXXXXXXXXXXXXXXXXXXXXX", "domain": "mydomain.mailgun.org" }
 ```
 
 You should edit _./test/data/fixture.json_ and modify the data to match your context.

docs/README.md

@@ -28,7 +28,7 @@ of the `error` object passed in the callback.
 See the `/docs` folder for detailed documentation. For full usage examples see the `/test` folder.
 
 ```js
-var api_key = 'key-XXXXXXXXXXXXXXXXXXXXXXX';
+var api_key = 'XXXXXXXXXXXXXXXXXXXXXXX';
 var domain = 'www.mydomain.com';
 var mailgun = require('mailgun-js')({apiKey: api_key, domain: domain});
 

docs/_sidebar.md

@@ -6,6 +6,8 @@
   - [Promises](/promises)
   - [Webhook Validation](/webhook)
   - [Email Validation](/email_validation)
+  - [Debug Logging](/debug)
+  - [Test Mode](/testmode)
   - [Tests](/tests)
 - API Reference
   - [Message](/api/message)

docs/debug.md

@@ -0,0 +1,7 @@
+## Debug logging
+
+[debug](https://npmjs.com/package/debug) package is used for debug logging.
+
+```sh
+DEBUG=mailgun-js node app.js
+```

docs/testmode.md

@@ -0,0 +1,69 @@
+## Test mode
+
+Test mode can be turned on using `testMode` option. When on, no requests are actually sent to Mailgun, rather we log the request options and applicable payload and form data. By default we log to `console.log`, unless `DEBUG` is turned on, in which case we use debug logging.
+
+```js
+mailgun = require('mailgun-js')({ apiKey: api_key, domain: domain, testMode: true })
+
+const data = {
+  from: 'mailgunjs+test1@gmail.com',
+  to: 'mailgunjstest+recv1@gmail.com',
+  subject: 'Test email subject',
+  text: 'Test email text'
+};
+
+mailgun.messages().send(data, function (error, body) {
+  console.log(body);
+});
+```
+
+```
+options: { hostname: 'api.mailgun.net',
+  port: 443,
+  protocol: 'https:',
+  path: '/v3/sandbox12345.mailgun.org/messages',
+  method: 'POST',
+  headers:
+   { 'Content-Type': 'application/x-www-form-urlencoded',
+     'Content-Length': 127 },
+  auth: 'api:key-0e8pwgtt5ylx0m94xwuzqys2-o0x4-77',
+  agent: false,
+  timeout: undefined }
+payload: 'to=mailgunjs%2Btest1%40gmail.com&from=mailgunjstest%2Brecv1%40gmail.com&subject=Test%20email%20subject&text=Test%20email%20text'
+form: undefined
+undefined
+```
+
+Note that in test mode no error or body are returned as a result.
+
+The logging can be customized using `testModeLogger` option which is a function to perform custom logging.
+
+```js
+const logger = (httpOptions, payload, form) => {
+  const { method, path } = httpOptions
+  const hasPayload = !!payload
+  const hasForm = !!form
+
+  console.log(`%s %s payload: %s form: %s`, method, path, hasPayload, hasForm)
+}
+
+mailgun = require('mailgun-js')({ apiKey: api_key, domain: domain, testMode: true, testModeLogger: logger })
+
+const data = {
+  from: 'mailgunjs+test1@gmail.com',
+  to: 'mailgunjstest+recv1@gmail.com',
+  subject: 'Test email subject',
+  text: 'Test email text'
+};
+
+mailgun.messages().send(data, function (error, body) {
+  console.log(body);
+});
+```
+
+Sample output:
+
+```
+POST /v3/sandbox12345.mailgun.org/messages payload: true form: false
+undefined
+```

docs/tests.md

@@ -3,7 +3,7 @@
 To run the test suite you must first have a Mailgun account with a domain setup. Then create a file named _./test/data/auth.json_, which contains your credentials as JSON, for example:
 
 ```json
-{ "api_key": "key-XXXXXXXXXXXXXXXXXXXXXXX", "public_api_key": "pubkey-XXXXXXXXXXXXXXXXXXXXXXX", "domain": "mydomain.mailgun.org" }
+{ "api_key": "XXXXXXXXXXXXXXXXXXXXXXX", "public_api_key": "XXXXXXXXXXXXXXXXXXXXXXX", "domain": "mydomain.mailgun.org" }
 ```
 
 You should edit _./test/data/fixture.json_ and modify the data to match your context.

lib/mailgun.js

@@ -29,19 +29,24 @@ class Mailgun {
     this.port = options.port || 443
     this.retry = options.retry || 1
 
+    this.testMode = options.testMode
+    this.testModeLogger = options.testModeLogger
+
     if (options.proxy) {
       this.proxy = options.proxy
     }
 
     this.options = {
-      'host': this.host,
-      'endpoint': this.endpoint,
-      'protocol': this.protocol,
-      'port': this.port,
-      'auth': this.auth,
-      'proxy': this.proxy,
-      'timeout': this.timeout,
-      'retry': this.retry
+      host: this.host,
+      endpoint: this.endpoint,
+      protocol: this.protocol,
+      port: this.port,
+      auth: this.auth,
+      proxy: this.proxy,
+      timeout: this.timeout,
+      retry: this.retry,
+      testMode: this.testMode,
+      testModeLogger: this.testModeLogger
     }
 
     this.mailgunTokens = {}

lib/request.js

@@ -63,6 +63,9 @@ class Request {
     this.proxy = options.proxy
     this.timeout = options.timeout
     this.retry = options.retry || 1
+    this.testMode = options.testMode
+    this.testModeLogger = typeof options.testModeLogger === 'function'
+      ? options.testModeLogger : this.defaultTestModeLogger
   }
 
   _request (method, resource, data, fn) {
@@ -129,6 +132,11 @@ class Request {
       opts.agent = new ProxyAgent(this.proxy)
     }
 
+    if (this.testMode) {
+      this.testModeLogger(opts, this.payload, this.form)
+      return fn()
+    }
+
     if (typeof this.retry === 'object' || this.retry > 1) {
       retry(this.retry, (retryCb) => {
         this.callback = retryCb
@@ -372,6 +380,13 @@ class Request {
       req.end()
     }
   }
+
+  defaultTestModeLogger (httpOptions, payload, formData) {
+    const testlog = debug.enabled ? debug : console.log
+    testlog('options: %o', httpOptions)
+    testlog('payload: %o', payload)
+    testlog('form: %o', formData)
+  }
 }
 
 module.exports = Request