Testing a Connector

A connector has two things to test: that its ports do the right thing against the platform, and that the core does the right thing with the connector. The SDK ships fakes for the second, the kit for the shape of the first, and the platform's own client fake is yours to write for the rest.

The fake connector

Subscriby\Connector\Testing\FakeConnector is the reference implementation and the double every core path is tested against. Its manifest is the connector.json beside it, read through the same loader as every package, so the loader runs in every test and the file doubles as a worked example. It deliberately violates every assumption a single-platform core would make: 280-character messages with two buttons a row and no files, membership grants instead of invite links plus a creator_task kind, no early admission, three admin commands, a one-message-a-second pace, identities that look nothing like a chat id.

Subscriby's application registers it in its registry whenever tests run (and on any environment with connectors.fake switched on, which is how a staging site gets a demo project with no real platform). A core path that still assumes one platform fails against it; that is what keeps the core honest for the platform your connector brings.

The port fakes

Each fake implements one port, keeps what it was asked in memory and answers something plausible. Each also has a trigger: a value in the input that makes it fail the way a platform would, so both halves of a core path can be driven without a platform. Register them beside a real port of yours to test one port in isolation, or all of them to test a flow.

$messenger = new FakeMessenger;
$registrar->port(Messenger::class, $messenger);

// … drive the core path that should tell the member …

$messenger->assertSentTo('member-42', containing: 'Payment received');

What your own suite covers

Test each port against a fake of the platform's client (an HTTP fake for a REST platform, a recorded socket for a gateway), never against the live platform, and pin the wire format the way Subscriby pins the Telegram connector's: characterisation tests that record what the connector sends for each core message and each admin flow, and fail on any change, so a behaviour change is a deliberate commit with a justification rather than a surprise.

For the core's side, register your connector beside the fake in a Subscriby test run and assert the same scenario on both: a purchase grants, a cancellation revokes, a member with no identity waits as pending_identity and materialises after a handshake. If the core behaves differently for yours, either your manifest says something the fake's does not, or the core has a platform assumption left, and either is worth a report.

Running the kit

The kit needs a ConnectorRegistry, and the SDK ships one for exactly this: Subscriby\Connector\Testing\TestRegistry. Register the manifest and the connector into it, hand it to the suite and assert the report, all inside your package's own test suite with no Subscriby checkout:

use Subscriby\Connector\Manifest\ManifestFile;
use Subscriby\Connector\Testing\Conformance\ConformanceSuite;
use Subscriby\Connector\Testing\TestRegistry;

it('passes the conformance kit', function (): void {
    $registry = new TestRegistry;
    $registry->register(ManifestFile::load(dirname(__DIR__).'/connector.json'), new ExampleConnector);

    $report = (new ConformanceSuite($registry))->run('example', packagePath: dirname(__DIR__));

    expect($report->passed())->toBeTrue($report->summary());
});

TestRegistry::register() runs the same manifest-to-port checks the application's registry runs at boot, through the same class (Subscriby\Connector\Registry\PortAgreement): a capability without its port, a port without its capability, a missing required port, or install fields both declared in the file and bound as a SettingsSchema throw InvalidManifest with the words production would use, before a single rule runs. What the application reads from configuration is a constructor argument here: official (a connector declaring native_payments passes official: ['example'] or is refused), available (every registered key by default) and disabled. A form declared in the file comes back through a passthrough translator, so labels read as you wrote them. The rules that need the application's own behaviour (the per-installation capability switches, the inbound gate) are not in the kit, so this run is complete for what the kit checks.

The other way is inside Subscriby's suite: put your package under packages/subscriby-connector-<key>/ in a checkout of Subscriby; its Pest configuration includes every packages/subscriby-connector-*/tests directory, your service provider boots with the application, and a test of yours runs the suite against app(ConnectorRegistry::class) exactly as the first-party connectors do. That checkout is also where the core's side is tested against your connector: a purchase grants, a cancellation revokes, a member with no identity waits.

Whichever way you run it, three checks need no registry at all and belong in every package's suite from the first commit: ManifestFile::load(__DIR__.'/../connector.json') for the manifest, MigrationRules::violations('<key>', __DIR__.'/../database/migrations') for the data rules, and the Field and MessageAction constructors for your forms and buttons.

What only the platform proves

The kit and the fakes cannot tell you that a real bot can add a real member to a real room, that the platform's rate limit is where its documentation says, or that a revoked token answers the way you classified it. Keep one sandbox installation on the platform, run the connector against it by hand before each release, and record what you see into the characterisation snapshots.