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

This commit is contained in:
AJ ONeal 2019-06-06 23:04:51 -06:00
parent f2373a09de
commit 17e409b158
3 changed files with 117 additions and 101 deletions

View File

@ -19,20 +19,31 @@ npm install --save-dev acme-challenge-test@3.x
## Usage ## Usage
```js ```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-http-01-cli').create({});
//var challenger = require('acme-dns-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' YOUR_TOKEN_OPTION: 'SOME_API_KEY'
}); });
// The dry-run tests can pass on, literally, 'example.com' // The dry-run tests can pass on, literally, 'example.com'
// but the integration tests require that you have control over the domain // 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-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) - [`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 ## Example
@ -62,7 +77,7 @@ var tester = require('acme-challenge-test');
var domain = 'example.com'; var domain = 'example.com';
tester tester
.test('http-01', domain, { .testRecord('http-01', domain, {
// Should set a TXT record for dnsHost with dnsAuthorization and ttl || 300 // Should set a TXT record for dnsHost with dnsAuthorization and ttl || 300
set: function(opts) { set: function(opts) {
console.log('set opts:', 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 ```js
tester tester
.test('dns-01', 'example.com', { .testZone('dns-01', 'example.com', {
set: function(opts) { set: function(opts) {
var ch = opts.challenge; var ch = opts.challenge;
// { type: 'dns-01' // or 'http-01' // { type: 'dns-01' // or 'http-01'
@ -167,7 +181,7 @@ var YourApi = function createApi(config) {
var request = require('@root/request'); var request = require('@root/request');
request = require('util').promisify(request); request = require('util').promisify(request);
return function (method, url, body) { return function(method, url, body) {
return request({ return request({
method: method, method: method,
url: url, url: url,
@ -178,8 +192,8 @@ var YourApi = function createApi(config) {
}).then(function(resp) { }).then(function(resp) {
return resp.body; return resp.body;
}); });
} };
} };
``` ```
### Two notes: ### Two notes:
@ -191,6 +205,6 @@ location on an http serever, set DNS records, or add the appropriate data to the
Note 2: 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`

View File

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

View File

@ -1,6 +1,6 @@
{ {
"name": "acme-challenge-test", "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.", "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", "main": "index.js",
"homepage": "https://git.rootprojects.org/root/acme-challenge-test.js", "homepage": "https://git.rootprojects.org/root/acme-challenge-test.js",