Runner Plugins

A runner plugin extends what happens around your tests. Logging in through AuthMe, adding an expect(player).toHaveBalance(100) matcher, resetting state between tests on a shared stand, shipping a suite of tests that any server running your plugin should pass — all of that is a plugin, and none of it requires the test engine to know about it. Plugins are declared per environment:

create("staging", ExternalMode) {
    plugins {
        npm("@plugwright/auth-authme") {
            options["loginCommand"] = "/log"
        }
        local("staging") {
            inheritTests = false
        }
    }
}

npm(...) names a published package, installed by plugwrightCompileTests along with the rest of the environment’s packages. local(...) names a plugin of your own: local("staging") is plugins/staging.ts in the test workspace, compiled to dist/plugins/staging.js by the same tsc run as your specs. For a plugin that lives outside the workspace there is still local(file("...")). Options are plain strings — anything secret belongs in accounts { }, where it stays a secret reference. LocalMode takes the same block. A local server running an authentication plugin needs the login hook exactly as much as a remote one does.

What a plugin can do

export interface PlugwrightPlugin<O = unknown> {
    name: string;
    apiVersion?: number;
    setup?(ctx: { session, env, options: O }): Promise<void> | void;
    onPlayerCreate?(player, ctx: { account, env }): Promise<void> | void;
    beforeEach?(ctx: TestContext): Promise<void> | void;
    afterEach?(ctx: TestContext): Promise<void> | void;
    extendContext?(ctx: TestContext): Record<string, unknown> | void;
    matchers?: Record<string, MatcherFn>;
    tests?: Array<{ file: string; mode: 'preflight' | 'suite' }>;
    cleanup?(ctx: { session, scope: 'session' | 'manual' }): Promise<void> | void;
    teardown?(): Promise<void> | void;
}

Order over one run:

env.setup() → console probe → load plugins → register matchers → plugins.setup()
  → preflight tests            (a failure here aborts the run)
  → user specs + suite tests
      per test: lease account → connect → onPlayerCreate → beforeEach
                → body → cleanup finalizers → afterEach → return account
  → reports → cleanup('session') → teardown() → env.teardown()

Matchers are merged into the shared prototype before the first spec file is imported. That ordering is not incidental: expect(x).toHaveBalance() looks the matcher up when it is called, but the spec file has to typecheck and import first.

Authentication is a hook, not a test

import { definePlugin, poll } from '@plugwright/runner';

export default definePlugin({
    name: 'authme',
    async onPlayerCreate(player, { account }) {
        // Whether AuthMe puts up a login wall for a premium account is a server-side
        // setting, not something derivable from `account.auth` — don't assume it away.
        // wait for the prompt, answer it, wait for the confirmation
    },
});

onPlayerCreate fires on every connection: the bot a test starts with, a second bot from createPlayer(), and every player.rejoin(). A “log in first” test fires once, in whatever order the spec files happen to load, and leaves every other connection unauthenticated. If you want the visible reassurance of a login test in the report, ship one as a preflight test alongside the hook.

Hooks and `describe.serial`

beforeEach and afterEach normally wrap every test. Around a describe.serial block they run once instead: before its first test and after its last. That is deliberate, and it matters most for a plugin that resets an account between tests. A block exists because its second test depends on what its first one did; a reset firing in between would throw that away, and the plugin has no way to tell which state the block was counting on. Anything a plugin needs to do per test inside a block belongs in the spec’s own beforeEach, where the test author can see it.

Inherited tests

tests: [
    { file: join(__dirname, 'auth.spec.js'), mode: 'preflight' },
    { file: join(__dirname, 'economy.spec.js'), mode: 'suite' },
]

preflight tests run before any user spec and abort the run when they fail — there is no point testing a shop when nobody can log in. suite tests run alongside your own and are tagged with the plugin’s name in the report. Spec discovery only looks at your own compiled tests directory, so this is the only way a packaged test ever runs. Per-plugin, inheritTests = false loads the hooks and matchers without the tests.

Fixtures

extendContext adds fields to the object every test destructures:

extendContext(ctx) {
    return { auth: new AuthApi(ctx.player) };
}

declare module '@plugwright/runner' {
    interface TestContext {
        auth: AuthApi;
    }
}

The declaration merging block is what gives you types and autocompletion at the call site. Without it the fixture still works, and TypeScript still complains.

Matchers

matchers: {
    async toHaveBalance(this: any, expected: number) {
        await this.pollAssertion(
            () => currentBalance(this.actual) === expected,
            () => `Expected NOT to have balance ${expected}`,
            () => `Expected balance ${expected}, got ${currentBalance(this.actual)}`,
        );
    },
}

Anything that reads the server log has to check the console output level first, because a console that only answers its own commands leaves that buffer empty. See External Servers.

Versioning

export default definePlugin({ name: 'authme', apiVersion: 1 });

A plugin built against a newer contract than the runner supports fails to load with a message saying so. Leaving apiVersion unset skips the check.

Writing one

A plugin is an npm package (or a single compiled file) whose default export implements the interface:

import { definePlugin } from '@plugwright/runner';

export default definePlugin({
    name: 'staging-reset',

    async beforeEach({ player, server }) {
        if (!server.session.env.capabilities.console) return;

        // Reset permissions and clear inventory before letting the test start
        await player.deOp();
        await player.clearInventory();
    },
});

definePlugin is an identity function; it exists so TypeScript infers your options type at the definition site. Depend on @plugwright/runner as a peer dependency, ship compiled JavaScript, and point main at it. @plugwright/auth-authme in this repository is a complete, working example: a hook, an options interface, a preflight test, and a README.

Get Started

Documentation

Environments

Maintaining

What a plugin can do

Authentication is a hook, not a test

Hooks and `describe.serial`

Inherited tests

Fixtures

Matchers

Versioning

Writing one

​What a plugin can do

​Authentication is a hook, not a test

​Hooks and describe.serial

​Inherited tests

​Fixtures

​Matchers

​Versioning

​Writing one

What a plugin can do

Authentication is a hook, not a test

Hooks and `describe.serial`

Inherited tests

Fixtures

Matchers

Versioning

Writing one