v3.1.0: update docs, default to testing full zones

README.md

@@ -19,20 +19,31 @@ npm install --save-dev acme-challenge-test@3.x
 ## Usage
 
 ```js
-var tester = require("acme-challenge-test");
+var tester = require('acme-challenge-test');
 
 //var challenger = require('acme-http-01-cli').create({});
 //var challenger = require('acme-dns-01-cli').create({});
-var challenger = require("./YOUR-CHALLENGE-STRATEGY").create({
+var challenger = require('./YOUR-CHALLENGE-STRATEGY').create({
 	YOUR_TOKEN_OPTION: 'SOME_API_KEY'
 });
 
 // The dry-run tests can pass on, literally, 'example.com'
 // but the integration tests require that you have control over the domain
-var domain = "example.com";
+var zone = 'example.com';
 
-tester.test("http-01", domain, challenger).then(function() {
+tester.testZone('dns-01', zone, challenger).then(function() {
-	console.info("PASS");
+	console.info('PASS');
+});
+```
+
+**Note**: If the service you are testing only handles individual records
+(not multiple records in a zone), you can use `testRecord` instead:
+
+```js
+var record = 'foo.example.com';
+
+tester.testRecord('dns-01', record, challenger).then(function() {
+	console.info('PASS');
 });
 ```
 
@@ -44,7 +55,11 @@ which you should use as a model for any plugins that you create.
 - [`acme-http-01-cli`](https://git.rootprojects.org/root/acme-http-01-cli.js)
 - [`acme-dns-01-cli`](https://git.rootprojects.org/root/acme-dns-01-cli.js)
 
-You can find other implementations by searching npm for [acme-http-01-](https://www.npmjs.com/search?q=acme-http-01-) and [acme-dns-01-](https://www.npmjs.com/search?q=acme-dns-01-).
+You can find other implementations by searching npm for [acme-http-01-](https://www.npmjs.com/search?q=acme-http-01-)
+and [acme-dns-01-](https://www.npmjs.com/search?q=acme-dns-01-).
+
+If you are building a plugin, please let us know.
+We would like to co-author and help maintain and promote your module.
 
 ## Example
 
@@ -62,7 +77,7 @@ var tester = require('acme-challenge-test');
 var domain = 'example.com';
 
 tester
-  .test('http-01', domain, {
+	.testRecord('http-01', domain, {
 		// Should set a TXT record for dnsHost with dnsAuthorization and ttl || 300
 		set: function(opts) {
 			console.log('set opts:', opts);
@@ -107,8 +122,7 @@ Here's a quick pseudo stub-out of what a test-passing plugin object might look l
 
 ```js
 tester
-  .test('dns-01', 'example.com', {
+	.testZone('dns-01', 'example.com', {
-  
 		set: function(opts) {
 			var ch = opts.challenge;
 			// { type: 'dns-01' // or 'http-01'
@@ -167,7 +181,7 @@ var YourApi = function createApi(config) {
 	var request = require('@root/request');
 	request = require('util').promisify(request);
 
-  return function (method, url, body) {
+	return function(method, url, body) {
 		return request({
 			method: method,
 			url: url,
@@ -178,8 +192,8 @@ var YourApi = function createApi(config) {
 		}).then(function(resp) {
 			return resp.body;
 		});
-  }
+	};
-}
+};
 ```
 
 ### Two notes:
@@ -191,6 +205,6 @@ location on an http serever, set DNS records, or add the appropriate data to the
 
 Note 2:
 
-* When `altname` is `foo.example.com` the `dnsHost` will be `_acme-challenge.foo.example.com`
+- When `altname` is `foo.example.com` the `dnsHost` will be `_acme-challenge.foo.example.com`
-* When `altname` is `*.foo.example.com` the `dnsHost` will _still_ be `_acme-challenge.foo.example.com`!!
+- When `altname` is `*.foo.example.com` the `dnsHost` will _still_ be `_acme-challenge.foo.example.com`!!
-* When `altname` is `bar.foo.example.com` the `dnsHost` will be `_acme-challenge.bar.foo.example.com`
+- When `altname` is `bar.foo.example.com` the `dnsHost` will be `_acme-challenge.bar.foo.example.com`

index.js

@@ -179,7 +179,7 @@ function run(challenger, opts) {
 	});
 }
 
-module.exports.test = function(type, zone, challenger) {
+function testZone(type, zone, challenger) {
 	var domains = [zone, 'foo.' + zone];
 	if ('dns-01' === type) {
 		domains.push('*.foo.' + zone);
@@ -191,7 +191,7 @@ module.exports.test = function(type, zone, challenger) {
 			return;
 		}
 		console.info("TEST '%s'", domain);
-		return testOne(type, domain, challenger).then(function() {
+		return testRecord(type, domain, challenger).then(function() {
 			console.info("PASS '%s'", domain);
 			return next();
 		});
@@ -208,7 +208,7 @@ module.exports.test = function(type, zone, challenger) {
 	});
 };
 
-function testOne(type, altname, challenger) {
+function testRecord(type, altname, challenger) {
 	var expires = new Date(Date.now() + 10 * 60 * 1000).toISOString();
 	var token = crypto.randomBytes(8).toString('hex');
 	var thumb = crypto.randomBytes(16).toString('hex');
@@ -248,4 +248,6 @@ function testOne(type, altname, challenger) {
 	return run(challenger, { challenge: challenge });
 }
 
-module.exports._test = testOne;
+module.exports.testRecord = testRecord;
+module.exports.testZone = testZone;
+module.exports.test = testZone;

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "acme-challenge-test",
-	"version": "3.0.5",
+	"version": "3.1.0",
 	"description": "The base set of tests for all ACME challenge strategies. Any `acme-http-01-`, `acme-dns-01-`, `acme-challenge-`, or greenlock plugin should be able to pass these tests.",
 	"main": "index.js",
 	"homepage": "https://git.rootprojects.org/root/acme-challenge-test.js",