Loading

Set up Scout in your plugin or package

This page shows the minimum setup to add Scout tests to a plugin/package. For choosing the right import (@kbn/scout vs solution packages), see Scout packages.

  1. Generate a working scaffold

    Generate a working scaffold (folders, configs, and sample tests) by following the guided setup:

    node scripts/scout.js generate

    This command will also automatically enable your plugin or package's Scout tests in the CI by updating the .buildkite/scout_ci_config.yml file.

  2. Write and run tests

    Tweak the new Playwright config(s) and write UI tests or API tests.

  1. Create the folder layout

    Create test/scout:

    your-plugin/
└── test/
    └── scout/
        ├── ui/
        ├── api/
        └── common/
    1. UI tests (optional)
    2. API tests (optional)
    3. shared code (optional)

  2. Create Playwright config(s)

    Create a config under test/scout/ui and/or test/scout/api.

    Create playwright.config.ts:

    import { createPlaywrightConfig } from '@kbn/scout';

export default createPlaywrightConfig({
  testDir: './tests',
});
    Important

    Use the conventional name playwright.config.ts so Scout tooling can discover the config.

    Then create the tests/ directory next to the config.

    If many files share one-time setup (archives/ingest/settings), add a global setup hook.

    If your UI suites can be isolated, add parallel.playwright.config.ts under test/scout/ui and point it at parallel_tests/:

    import { createPlaywrightConfig } from '@kbn/scout';

export default createPlaywrightConfig({
  testDir: './parallel_tests',
  workers: 2,
});
    Important

    Use the conventional name parallel.playwright.config.ts so Scout tooling can discover the config.

    Then create the parallel_tests/ directory next to the config. For parallel suites, prefer defining test suites and test cases using spaceTest so each worker runs in an isolated Space (see Parallelism).

    If many files share one-time setup (archives/ingest/settings), add a global setup hook.

  3. Enable Scout runs in CI

    Ensure your plugin or package is listed in .buildkite/scout_ci_config.yml so Scout tests run in CI. If not already in the list, add one line under the appropriate enabled list:

    • Plugins: Add - <plugin_name> under plugins.enabled. The name is the path segment(s) after plugins/ (the plugin folder name, or a slash-separated path for nested plugins).
    • Packages: Add - <package_name> under packages.enabled. The name is the folder name after packages/.
    plugins:
  enabled:
    - <plugin_name>
  disabled:

packages:
  enabled:
    - <package_name>
  disabled:

  4. Write and run tests

    Tweak the new Playwright config(s) and write UI tests or API tests.