Async Test And Doc Sync

Skill: async-test-and-doc-sync

Use this skill when adding or changing public behavior, updating builder validation or part semantics, writing or reviewing tests, updating PHPDoc blocks or guide pages, or touching anything user-facing enough that tests or docs should move with it.

This is alignment skill. Load it when the question is not "does the code work?" but "do tests prove it and do docs describe it?"

Goal

Keep tests, PHPDoc, and long-form documentation synchronized with the public behavior of parts, repositories, builders, and helpers:

• unit tests assert semantic behavior, not incidental implementation
• integration tests prove real async flows against Discord
• PHPDoc blocks serve as contract surface for IDEs and generated reference
• guide and docs pages reflect current recommended usage
• changes to public behavior always travel with their companion test and doc updates

Read in this order

1. tests/functions.php — wait() helper and getMockDiscord() factory
2. tests/DiscordTestCase.php — integration base class with real channel setup
3. tests/bootstrap.php — autoload, .env loading, singleton wiring
4. phpunit.xml — test suite configuration, coverage settings
5. Representative unit tests:
   • tests/Builders/ModalBuilderTest.php
   • tests/FunctionsTest.php
   • tests/CollectionsTest.php
6. Representative integration tests:
   • tests/Parts/Channel/ChannelTest.php
   • tests/Parts/Channel/Message/Embed/EmbedTest.php
   • tests/Parts/Channel/Message/MessageTest.php
7. guide/ — long-form RST documentation for parts, events, builders
8. docs/ — Gatsby site source for published documentation
9. README.md — getting started, installation, basic usage
10. CONTRIBUTING.md — contributor workflow and code style expectations

Core contract

Tests and docs in this repo are not afterthoughts. They form a contract surface:

• PHPDoc @property and @property-read annotations on parts are how IDEs and users discover magic properties. If code adds a fillable field or getter mutator without updating the docblock, the property is effectively invisible to consumers.
• Unit tests extend DiscordTestCase; use $this->getMockBuilder() for isolated class dependencies and getMockDiscord() when a lightweight real client is needed.
• Integration tests extending DiscordTestCase prove that async flows work against real Discord infrastructure. These require environment variables and a live bot token.
• Guide pages in guide/ and Gatsby pages in docs/ describe recommended patterns. They should only change when public behavior or preferred usage actually changes — not for internal refactors.

If a change touches public behavior but skips one of these surfaces, the contract is incomplete.

Unit tests vs integration tests

Unit tests

All unit-test classes must extend DiscordTestCase, including tests for logic isolated from Discord I/O:

• builder validation limits (content length, component counts, enum values)
• helper function behavior (contains(), studly(), escapeMarkdown(), poly_strlen())
• collection operations (push(), map(), filter(), from())
• part attribute hydration from raw arrays using getMockDiscord()
• serialization shape from jsonSerialize() on builders

Use $this->getMockBuilder() for isolated class dependencies and getMockDiscord() when a lightweight real client is needed. DiscordTestCase supplies the shared test lifecycle and skips cleanly when Discord integration is unavailable.

Example: tests/Builders/ModalBuilderTest.php uses $this->expectException(\LogicException::class) and str_repeat('a', 101) to verify title length validation.

Integration tests

Use wait() and return the wait() call when the test must interact with real Discord infrastructure — sending/editing/deleting messages, pinning, creating invites, fetching message history, verifying embed hydration, or testing repository fetch()/freshen() against live API.

These tests require DISCORD_TOKEN, TEST_CHANNEL, and TEST_CHANNEL_NAME in .env or environment. DiscordSingleton shares a single connected client across the suite. Reach the live channel only through $this->channel(): it skips the test when there is no token, so the rest of the class still runs offline. A test that needs Discord some other way should check self::isLive() and skip itself.

A test that sends a request should not need Discord at all: set getMockHttpDriver() on a getMockDiscord() client and assert on the requests it records, as tests/Parts/Guild/GuildRequestsTest.php does. Those run in CI on every push and pull request (.github/workflows/tests.yml).

The getMockDiscord() factory

Defined in tests/functions.php. Creates a minimal Discord instance with empty token and NullLogger — suitable for constructing parts and testing attribute access without connecting to gateway.

Use $this->getMockBuilder() for mocked class dependencies. Use getMockDiscord() for local client-backed tests; otherwise use and return wait() for asynchronous work.

Test suite organization

Directory layout

Test files mirror the source structure. Builder tests live in tests/Builders/, part tests in tests/Parts/{Family}/, and utility tests in tests/ root. Infrastructure files (bootstrap.php, functions.php, DiscordSingleton.php, DiscordTestCase.php) live at the tests/ root.

Where to place new tests

• Builder tests → tests/Builders/{BuilderName}Test.php
• Part tests → tests/Parts/{Family}/{PartName}Test.php
• Helper/utility tests → tests/ root
• All unit tests extend DiscordTestCase

phpunit.xml

Discovers all *Test.php under tests/ recursively. Coverage tracks src/. Bootstrap is tests/bootstrap.php.

Async testing patterns

The wait() bridge

wait() in tests/functions.php bridges Promise-based async code into synchronous PHPUnit assertions:

function wait(callable $callback, float $timeout = TIMEOUT, ?callable $timeoutFn = null)

It works by scheduling $callback on the ReactPHP loop via futureTick(), passing a $resolve callable that stops the loop and captures the result, adding a timeout timer (default 10s), running the loop synchronously, and re-throwing any captured exception after loop stops.

Common assertion patterns in integration tests

Promise chain with assertion then resolve:

return wait(function (Discord $discord, $resolve) {
    $this->channel()->sendMessage('test content')
        ->then(fn (Message $m) => $this->assertEquals('test content', $m->content))
        ->then($resolve, $resolve);
});

Custom timeout with fallback:

return wait(function (Discord $discord, $resolve) {
    // ... async work ...
}, 10, fn () => $this->markTestIncomplete('Hit rate limit.'));

Key rules:

• always pass $resolve as both fulfillment and rejection handler at the end of the chain
• the $callback receives (Discord $discord, callable $resolve) — use $discord for client access
• return the wait() call from the test method so PHPUnit tracks it
• default timeout is 10 seconds (TIMEOUT constant)

PHPDoc as contract surface

What to document

Every part class should have class-level docblock annotations for @property (read/write magic properties from $fillable), @property-read (computed properties from mutators or repos), @method (delegated magic methods), @since (version introduced), and @link (Discord API docs URL).

Why this matters

PHPDoc in this repo serves three purposes: IDE autocompletion (consumers rely on @property since all access goes through __get()), generated reference (docs tooling reads annotations), and static analysis (Mago uses docblocks for type checking).

When to update docblocks

• new field added to $fillable → add @property with type
• new getter mutator added → add @property-read with return type
• new repository exposed in $repositories → add @property-read for the repository type
• field removed or deprecated → update or remove annotation
• type changed (e.g., string to ?string) → update annotation