Skip to main content
JUMP TO:Quick StartCLI CommandsConfigurationPlaywright APIMCP ServerGitHub Actions
Guides / Custom Plugins(19 of 37)

Custom Plugins

Extend the CLI pipeline by selecting authentication storage state before rendering, transforming captured results, or sending a report after a run.

9-Hook Plugin Execution Pipeline
FIG 01 · 9-HOOK PLUGIN PIPELINE — SETUP · DISCOVER · RENDER · COMPARE · RUN · ERROR & REVERSE TEARDOWN

Interface

Plugins are objects implementing FrontguardPlugin. Import that type from @frontguard/cli/plugins to check hook arguments and return values against your installed version.

Lifecycle

Hooks run in registration order; teardown runs in reverse order. Hooks receive configuration or captured results, not a live Playwright Page.

Hook OrderHook NameWhen It Fires & Practical Use
01setup(ctx)Validate options and initialize state before discovery.
02beforeDiscover(config)Return the config to use for discovery.
03afterDiscover(routes, config)Return the routes to render after filtering or adding entries.
04beforeRender({ routes, config })Return { routes, config } to change capture configuration.
05afterRender(screenshots, ctx)Receives ScreenshotResult[]. Return a replacement array or void.
06afterCompare(diffs, ctx)Receives DiffResult[]. Return a replacement array or void.
07afterRun(result, ctx)Receives RunResult, including result.summary, before reporting.
08onError(error, stage)Handle a pipeline error; return true to suppress it.
09teardown()Release resources at the end of the run.

Practical plugin examples

Example 1: Selecting authentication storage state

Create a Playwright storage-state file using your application login flow first. It can contain cookies and localStorage. Return its path in the capture config:

frontguard.config.ts: selecting a saved session
import type { FrontguardPlugin } from '@frontguard/cli/plugins'

const sessionPlugin: FrontguardPlugin = {
  name: 'use-review-session',
  beforeRender({ routes, config }) {
    return {
      routes,
      config: { ...config, auth: { storageState: './playwright/.auth/user.json' } },
    }
  },
}

export default {
  version: 1,
  baseUrl: 'http://localhost:3000',
  routes: ['/dashboard', '/billing'],
  plugins: [sessionPlugin],
}

Example 2: Posting a JSON webhook summary

frontguard.config.ts: custom webhook reporter plugin
import type { FrontguardPlugin } from '@frontguard/cli/plugins'

const webhookPlugin: FrontguardPlugin = {
  name: 'custom-ci-webhook',
  async afterRun(result) {
    const { summary } = result
    if (summary.regressions > 0 && process.env.CI_ALERT_URL) {
      const response = await fetch(process.env.CI_ALERT_URL, {
        method: 'POST',
        headers: { 'content-type': 'application/json' },
        body: JSON.stringify({
          regressions: summary.regressions,
          totalComparisons: summary.total,
        }),
      })
      if (!response.ok) throw new Error('Alert delivery failed')
    }
  },
}

export default {
  version: 1,
  baseUrl: 'http://localhost:3000',
  plugins: [webhookPlugin],
}

Compatibility

Pin the CLI version and test your plugin against it. Destructuring afterRun({ summary }) is also valid because summary is a RunResult property. Each hook has a configurable timeout (30 seconds by default).