Development

Development

Clone https://github.com/RegionallyFamous/relay.git. Use PHP 7.4+ for syntax/model checks and Node 22 for the development tools. The plugin itself has no npm runtime dependencies.

npm ci
php tests/merge.php
php -l relay.php
php -l apps/relay/relay.os.php
node --check assets/inbox.js
node --check apps/relay/relay-client.js
python3 scripts/package.py

The package script produces dist/relay-0.3.0.zip and a self-contained dist/blueprint.json for WordPress Playground. Only the plugin entry, store/provenance classes, uninstall handler, assets, app files, license, and user documentation enter the install ZIP. Tests, fixture code, screenshots, package manifests, and dependencies do not.

Real WordPress integration tests

npm run test:integration
RELAY_WP=6.4 RELAY_PHP=7.4 npm run test:integration
RELAY_WP=latest RELAY_PHP=8.4 npm run test:integration
OPENSTATION_PATH=/absolute/path/to/openstation npm run test:integration
RELAY_MULTISITE=1 OPENSTATION_PATH=/absolute/path/to/openstation npm run test:integration

These create disposable WordPress installations, use actual WordPress APIs, and write machine-readable reports under tests/evidence/. Never load tests/integration.php into a production site: it creates test users and, in multisite, a test site.

Browser tests

Start the standard demo:

npx wp-playground server --wp=6.8 --php=8.3 --port=9427 \
  --mount="$PWD:/wordpress/wp-content/plugins/relay" \
  --blueprint="$PWD/tests/blueprint.json"
npm test

The native browser suite expects a disposable OpenStation site on port 9428. Activate both plugins, enable OpenStation for the demo administrator (desktop_mode_mode user meta equals '1'), and use the same notice fixtures. Mount an OpenStation checkout with its built assets. npm run test:native tests that site; RELAY_NATIVE_URL overrides its admin URL. A modern OpenStation checkout is required; a historical version with the same plugin version string may not contain the experimental App Framework.

On macOS browser tests use installed Google Chrome by default. Set CHROME_PATH for another executable; browser test helpers also support Playwright's bundled Chromium when that variable is omitted outside macOS.

npm run test:extended exercises the standard inbox's security responses, failed requests, keyboard use, accessibility, mobile widths, large batches, and concurrent collection. Both browser suites use synthetic notices, never a production site's data.

Compatibility

OpenStation's supported third-party client API avoids a Vite alias, framework fork, or copied UI library. Native app code lives in apps/relay/. WordPress's ordinary inbox remains in assets/inbox.js; both routes use Station_Inbox::change() and the same data.

The historical station_inbox_* AJAX and metadata names remain stable to preserve data from the first preview. The public product, app id, plugin folder, and text domain are Relay.

For an automatically started and stopped test site, run node scripts/test-browser.mjs. To run the native suite the same way, use OPENSTATION_PATH=/absolute/path/to/openstation node scripts/test-browser.mjs --native. Ports 9427 and 9428 must be free respectively.

Real plugin lab (Docker + MariaDB)

tests/compose.yml binds WordPress only to 127.0.0.1:9430. Mount a built OpenStation checkout using OPENSTATION_PATH. Its database and administrator credentials are disposable test values. The plugin and OpenStation source mounts are read-only. Never point the real-app tests at a production installation: they reset the lab administrator's Relay history and create test content.

OPENSTATION_PATH=/absolute/path/to/openstation bash scripts/setup-real-lab.sh
OPENSTATION_PATH=/absolute/path/to/openstation node tests/real-app.cjs
node tests/native-settings.cjs

The lab uses administrator relayadmin, password relay-local-test-only, URL http://127.0.0.1:9430, and /usr/local/bin/wp in the WordPress container. Run the settings suite after the real-app suite: its final test deletes that test user's personal history. Use docker compose -f tests/compose.yml down with the same OpenStation environment to stop the lab. Its named volumes retain test data unless you deliberately remove this lab's volumes.

Publisher API

add_action('init', function () {
    if (function_exists('relay_register_sender')) {
        relay_register_sender('my-plugin', 'My Plugin');
    }
});
add_action('admin_notices', function () {
    $attrs = function_exists('relay_notice_attributes')
        ? relay_notice_attributes('my-plugin', 'promotion') : '';
    echo '<div class="notice notice-info"' . $attrs . '><p>Try our optional upgrade.</p></div>';
});

The attributes helper returns escaped attributes. Register the same sender on AJAX requests too, not only while rendering the admin notice. Most ordinary PHP notice callbacks receive a plugin label automatically; the API is useful for custom publishers and explicit promotion classification. Relay still applies its conservative collection scope and visibility rules.