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
```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() {
console.info("PASS");
tester.testZone('dns-01', zone, challenger).then(function() {
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 _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 `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 `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];
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;

View File

@ -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",