Testing
Testing Domain Connect
Everything the module does goes through three seams: the Resolver (DNS), the
Transport (HTTPS), and the Signer. Each has a fake, so a test needs no network
and no private key.
FakeTransport
Cbox\Dns\DomainConnect\Testing\FakeTransport answers GET requests from stubs:
use Cbox\Dns\DomainConnect\Testing\FakeTransport;
$http = (new FakeTransport)
->stub('https://dc.provider.example/v2/acme.example/settings', 200, [
'providerId' => 'provider.example',
'providerName' => 'Provider',
'urlSyncUX' => 'https://connect.provider.example',
]) // an array body is JSON-encoded
->strict(); // an unstubbed URL throws instead of failing quietly
$http->requests(); // every URL requested, in order
$http->pinned(); // URL => the address it was pinned to (null: not pinned)
$http->assertRequested('https://dc.provider.example/v2/acme.example/settings');
Without strict(), an unstubbed URL gets a status-0 response, which is how a
transport reports a failure.
FakeSigner
Cbox\Dns\DomainConnect\Testing\FakeSigner returns a fixed signature,
FakeSigner::SIGNATURE (ZmFrZS1zaWc=), and records every query it signed in
signed(). Assert on the exact query string that would have been signed without
handling a key. The real signer is tested against a committed test-only keypair; see
Signing.
InteractsWithDomainConnect
Cbox\Dns\DomainConnect\Testing\InteractsWithDomainConnect builds on
InteractsWithDns (so fakeDns() and stubZone()
are there too) and adds:
fakeTransport()— a sharedFakeTransportfor the test;fakeSigner()— a sharedFakeSigner;domainConnect(string $keyHost = '_dcpubkeyv1')— aDomainConnectwired over the fake resolver, transport and signer.
It builds the module with Dns::domainConnect(..., allowNonPublicHosts: true), so
discovery runs with the address check off: no A/AAAA stubs are needed for the provider's
hosts, and requests are not pinned. To test the address check and the pinning,
build a Discoverer yourself with allowNonPublicHosts: false.
End to end
use Cbox\Dns\DomainConnect\ApplyRequest;
use Cbox\Dns\DomainConnect\Template;
use Cbox\Dns\DomainConnect\Testing\InteractsWithDomainConnect;
use Cbox\Dns\Enums\RecordType;
uses(InteractsWithDomainConnect::class);
it('discovers, builds a signed apply URL and checks the records', function (): void {
$template = Template::fromJson(<<<'JSON'
{
"providerId": "example.com",
"providerName": "Example",
"serviceId": "mail",
"serviceName": "Example mail",
"version": 1,
"syncPubKeyDomain": "example.com",
"records": [
{ "type": "TXT", "host": "_verify", "data": "token=%token%", "ttl": 3600 }
]
}
JSON);
// The customer's zone: delegation, SOA, and the _domainconnect pointer.
$this->stubZone('acme.example', ['ns1.acme.example' => '192.0.2.1'])
->stub('acme.example', RecordType::SOA, ['ns1.acme.example. hostmaster.acme.example. 1 7200 3600 1209600 300'])
->stub('_domainconnect.acme.example', RecordType::TXT, ['dc.provider.example']);
// The DNS provider's settings document and template-support answer.
$this->fakeTransport()
->strict()
->stub('https://dc.provider.example/v2/acme.example/settings', 200, [
'providerId' => 'provider.example',
'providerName' => 'Provider',
'urlSyncUX' => 'https://connect.provider.example',
'urlAPI' => 'https://api.provider.example',
])
->stub('https://api.provider.example/v2/domainTemplates/providers/example.com/services/mail', 200, '');
$dc = $this->domainConnect();
$discovery = $dc->discover('acme.example', $template);
expect($discovery->isAvailable())->toBeTrue()
->and($discovery->supportsTemplate())->toBeTrue();
$url = $dc->applyUrl(
new ApplyRequest($template, $discovery->zone, ['token' => 'abc123'], state: 'opaque-state'),
$discovery->settings,
);
expect($url)->toBe('https://connect.provider.example/v2/domainTemplates/providers/example.com/services/mail/apply'
.'?domain=acme.example&state=opaque-state&token=abc123&sig=ZmFrZS1zaWc%3D&key=_dcpubkeyv1')
->and($this->fakeSigner()->signed())->toBe(['domain=acme.example&state=opaque-state&token=abc123']);
// After the customer applied the template, the record is live at the zone's nameserver.
$this->fakeDns()->stub('_verify.acme.example', RecordType::TXT, ['token=abc123'], nameserver: '192.0.2.1');
$report = $dc->check($dc->recordSet($template, $discovery->zone, ['token' => 'abc123']));
expect($report->passed())->toBeTrue()
->and($report->findings[0]->check)->toBe('domain-connect.present')
->and($dc->outcome(['state' => 'opaque-state'])->succeeded())->toBeTrue()
->and($dc->outcome(['state' => 'opaque-state', 'error' => 'access_denied'])->succeeded())->toBeFalse();
});
The package's own tests/Unit/DomainConnect/DomainConnectTest.php follows the same
shape with the fixture template in tests/Fixtures/domain-connect/.