Testing

Kibana primarily uses Jest for unit testing. Each plugin or package defines a jest.config.js that extends a preset provided by the @kbn/test package. Unless you intend to run all unit tests within the project, it’s most efficient to provide the Jest configuration file for the plugin or package you’re testing.

yarn jest --config src/plugins/dashboard/jest.config.js

A script is available to provide a better user experience when testing while navigating throughout the repository. To run the tests within your current working directory, use yarn test:jest. Like the Jest CLI, you can also supply a path to determine which tests to run.

kibana/src/plugins/dashboard/server$ yarn test:jest #or
kibana/src/plugins/dashboard$ yarn test:jest server #or
kibana$ yarn test:jest src/plugins/dashboard/server

Any additional options supplied to test:jest will be passed onto the Jest CLI with the resulting Jest command always being outputted.

kibana/src/plugins/dashboard/server$ yarn test:jest --coverage

# is equivelant to

yarn jest --coverage --verbose --config /home/tyler/elastic/kibana/src/plugins/dashboard/jest.config.js server

You can generate code coverage report for a single plugin.

yarn jest --coverage --config src/plugins/console/jest.config.js

Html report is available in target/kibana-coverage/jest/path/to/plugin

Check out Functional Testing to learn more about how you can run and develop functional tests for Kibana core and plugins.

You can also look into the Scripts README.md to learn more about using the node scripts we provide for building Kibana, running integration tests, and starting up Kibana and Elasticsearch while you develop.

We use functional tests to make sure the Kibana UI works as expected. It replaces hours of manual testing by automating user interaction. To have better control over our functional test environment, and to make it more accessible to plugin authors, Kibana uses a tool called the FunctionalTestRunner.

The FunctionalTestRunner is very bare bones and gets most of its functionality from its config file. If you’re writing a plugin outside the Kibana repo, you will have your own config file. See Functional Tests for Plugins outside the Kibana repo for more info.

There are three ways to run the tests depending on your goals:

When run without any arguments the FunctionalTestRunner automatically loads the configuration in the standard location, but you can override that behavior with the --config flag. List configs with multiple --config arguments.

There are also command line flags for --bail and --grep, which behave just like their mocha counterparts. For instance, use --grep=foo to run only tests that match a regular expression.

Logging can also be customized with --quiet, --debug, or --verbose flags.

Use the --help flag for more options.

The tests are written in mocha using @kbn/expect for assertions.

We use WebDriver Protocol to run tests in both Chrome and Firefox with the help of chromedriver and geckodriver. When the FunctionalTestRunner launches, remote service creates a new webdriver session, which starts the driver and a stripped-down browser instance. We use browser service and webElementWrapper class to wrap up Webdriver API.

The FunctionalTestRunner automatically transpiles functional tests using babel, so that tests can use the same ECMAScript features that Kibana source code uses. Refer to style_guides/js_style_guide.md.

Provider:

Code run by the FunctionalTestRunner is wrapped in a function so it can be passed around via config files and be parameterized. Any of these Provider functions may be asynchronous and should return/resolve-to the value they are meant to provide. Provider functions will always be called with a single argument: a provider API (see the Provider API Section).

A config provider:

// config and test files use `export default`
export default function (/* { providerAPI } */) {
  return {
    // ...
  }
}

// on CI test suite will be run twice: in Chrome and Firefox
describe('My Cross-browser Test Suite', function () {
  this.tags('includeFirefox');

  it('My First Test');
}

If the tests do not apply to Firefox, assign the skipFirefox tag.

To run tests on Firefox locally, use config.firefox.js:

node scripts/functional_test_runner --config test/functional/config.firefox.js

Tests should run at the positive security boundry condition, meaning that they should be run with the mimimum privileges required (and documented) and not as the superuser. This prevents the type of regression where additional privleges accidentally become required to perform the same action.

The functional UI tests now default to logging in with a user named test_user and the roles of this user can be changed dynamically without logging in and out.

In order to achieve this a new service was introduced called createTestUserService (see link:test/common/services/security/test_user.ts). The purpose of this test user service is to create roles defined in the test config files and setRoles() or restoreDefaults().

An example of how to set the role like how its defined below:

await security.testUser.setRoles(['kibana_user', 'kibana_date_nanos']);

Here we are setting the test_user to have the kibana_user role and also role access to a specific data index (kibana_date_nanos).

Tests should normally setRoles() in the before() and restoreDefaults() in the after().

This annotated example file shows the basic structure every test suite uses. It starts by importing @kbn/expect and defining its default export: an anonymous Test Provider. The test provider then destructures the Provider API for the getService() and getPageObjects() functions. It uses these functions to collect the dependencies of this suite. The rest of the test file will look pretty normal to mocha.js users. describe(), it(), before() and the lot are used to define suites that happen to automate a browser via services and objects of type PageObject.

import expect from '@kbn/expect';
// test files must `export default` a function that defines a test suite
export default function ({ getService, getPageObject }) {

  // most test files will start off by loading some services
  const retry = getService('retry');
  const testSubjects = getService('testSubjects');
  const esArchiver = getService('esArchiver');

  // for historical reasons, PageObjects are loaded in a single API call
  // and returned on an object with a key/value for each requested PageObject
  const PageObjects = getPageObjects(['common', 'visualize']);

  // every file must define a top-level suite before defining hooks/tests
  describe('My Test Suite', () => {

    // most suites start with a before hook that navigates to a specific
    // app/page and restores some archives into {es} with esArchiver
    before(async () => {
      await Promise.all([
        // start with an empty .kibana index
        esArchiver.load('test/functional/fixtures/es_archiver/empty_kibana'),
        // load some basic log data only if the index doesn't exist
        esArchiver.loadIfNeeded('test/functional/fixtures/es_archiver/makelogs')
      ]);
      // go to the page described by `apps.visualize` in the config
      await PageObjects.common.navigateTo('visualize');
    });

    // right after the before() hook definition, add the teardown steps
    // that will tidy up {es} for other test suites
    after(async () => {
      // we unload the empty_kibana archive but not the makelogs
      // archive because we don't make any changes to it, and subsequent
      // suites could use it if they call `.loadIfNeeded()`.
      await esArchiver.unload('test/functional/fixtures/es_archiver/empty_kibana');
    });

    // This series of tests illustrate how tests generally verify
    // one step of a larger process and then move on to the next in
    // a new test, each step building on top of the previous
    it('Vis Listing Page is empty');
    it('Create a new vis');
    it('Shows new vis in listing page');
    it('Opens the saved vis');
    it('Respects time filter changes');
    it(...
  });

}

The first and only argument to all providers is a Provider API Object. This object can be used to load service/page objects and config/test files.

Within config files the API has the following properties

Within service and PageObject Providers the API is:

Within a test Provider the API is exactly the same as the service providers API but with an additional method:

The FunctionalTestRunner comes with three built-in services:

The Kibana functional tests define the vast majority of the actual functionality used by tests.

Full list of services that are used in functional tests can be found here: test/functional/services

Services are intentionally generic. They can be literally anything (even nothing). Some services have helpers for interacting with a specific types of UI elements, like pointSeriesVis, and others are more foundational, like log or config. Whenever you want to provide some functionality in a reusable package, consider making a custom service.

To create a custom service somethingUseful:

The purpose for each PageObject is pretty self-explanatory. The visualize PageObject provides helpers for interacting with the visualize app, dashboard is the same for the dashboard app, and so on.

One exception is the "common" PageObject. A holdover from the intern implementation, the common PageObject is a collection of helpers useful across pages. Now that we have shareable services, and those services can be shared with other FunctionalTestRunner configurations, we will continue to move functionality out of the common PageObject and into services.

Please add new methods to existing or new services rather than further expanding the CommonPage class.

Remember that you can’t run an individual test in the file (it block) because the whole describe needs to be run in order. There should only be one top level describe in a file.

Another important gotcha is writing stable tests by being mindful of timing. All methods on remote run asynchronously. It’s better to write interactions that wait for changes on the UI to appear before moving onto the next step.

For example, rather than writing an interaction that simply clicks a button, write an interaction with the a higher-level purpose in mind:

Bad example: PageObjects.app.clickButton()

class AppPage {
  // what can people who call this method expect from the
  // UI after the promise resolves? Since the reaction to most
  // clicks is asynchronous the behavior is dependant on timing
  // and likely to cause test that fail unexpectedly
  async clickButton () {
    await testSubjects.click(‘menuButton’);
  }
}

Good example: PageObjects.app.openMenu()

class AppPage {
  // unlike `clickButton()`, callers of `openMenu()` know
  // the state that the UI will be in before they move on to
  // the next step
  async openMenu () {
    await testSubjects.click(‘menuButton’);
    await testSubjects.exists(‘menu’);
  }
}

Writing in this way will ensure your test timings are not flaky or based on assumptions about UI updates after interactions.

From the command line run:

node --debug-brk --inspect scripts/functional_test_runner

This prints out a URL that you can visit in Chrome and debug your functional tests in the browser.

You can also see additional logs in the terminal by running the FunctionalTestRunner with the --debug or --verbose flag. Add more logs with statements in your tests like

// load the log service
const log = getService(‘log’);

// log.debug only writes when using the `--debug` or `--verbose` flag.
log.debug(‘done clicking menu’);

macOS users on a machine with a discrete graphics card may see significant speedups (up to 2x) when running tests by changing your terminal emulator’s GPU settings. In iTerm2: * Open Preferences (Command + ,) * In the General tab, under the "Magic" section, ensure "GPU rendering" is checked * Open "Advanced GPU Settings…​" * Uncheck the "Prefer integrated to discrete GPU" option * Restart iTerm

If your functional tests are flaky then the Operations team might skip them and ask that you make them less flaky before enabling them once again. This process usually involves looking at the failures which are logged on the relevant Github issue and finding incorrect assumptions or conditions which need to be awaited at some point in the test. To determine if your changes make the test fail less often you can run your tests in the Flaky Test Runner. This tool runs up to 500 executions of a specific ciGroup. To start a build of the Flaky Test Runner create a PR with your changes and then visit https://ci-stats.kibana.dev/trigger_flaky_test_runner, select your PR, choose the CI Group that your tests are in, and trigger the build.

This will take you to Buildkite where your build will run and tell you if it failed in any execution.

A flaky test may only fail once in 1000 runs, so keep this in mind and make sure you use enough executions to really prove that a test isn’t flaky anymore.

Kibana is doing unit testing using Jest.

Jest tests are stored in the same directory as source code files with the .test.{js,mjs,ts,tsx} suffix.

Each plugin and package contains it’s own jest.config.js file to define its root, and any overrides to the jest-preset provided by @kbn/test. When working on a single plugin or package, you will find it’s more efficient to supply the Jest configuration file when running.

yarn jest --config src/plugins/discover/jest.config.js

In order to write those tests there are two main things you need to be aware of. The first one is the different between jest.mock and jest.doMock and the second one our jest mocks file pattern. As we are running js and ts test files with babel-jest both techniques are needed specially for the tests implemented on Typescript in order to benefit from the auto-inference types feature.

Both methods are essentially the same on their roots however the jest.mock calls will get hoisted to the top of the file and can only reference variables prefixed with mock. On the other hand, jest.doMock won’t be hoisted and can reference pretty much any variable we want, however we have to assure those referenced variables are instantiated at the time we need them which lead us to the next section where we’ll talk about our jest mock files pattern.

Specially on typescript it is pretty common to have in unit tests jest.doMock calls which reference for example imported types. Any error will thrown from doing that however the test will fail. The reason behind that is because despite the jest.doMock isn’t being hoisted by babel-jest the import with the types we are referencing will be hoisted to the top and at the time we’ll call the function that variable would not be defined.

In order to prevent that we develop a protocol that should be followed:

The standard yarn test task runs several sub tasks and can take several minutes to complete, making debugging failures pretty painful. In order to ease the pain specialized tasks provide alternate methods for running the tests.

You could also add the --debug option so that node is run using the --debug-brk flag. You’ll need to connect a remote debugger such as node-inspector to proceed in this mode.

Even when using Kibana plugin generator we do not enforce a way for unit testing your plugin. Please setup and you use the tools of your choice. If the plugin will live inside the Kibana repo Jest must be used.

To write an accessibility test, use the provided accessibility service getService('a11y'). Accessibility tests are fairly straightforward to write as axe does most of the heavy lifting. Navigate to the UI that you need to test, then call testAppSnapshot(); from the service imported earlier to make sure axe finds no failures. Navigate through every portion of the UI for the best coverage.

An example test might look like this:

export default function ({ getService, getPageObjects }) {
  const { common, home } = getPageObjects(['common', 'home']);
  const a11y = getService('a11y'); /* this is the wrapping service around axe */

  describe('Kibana Home', () => {
    before(async () => {
      await common.navigateToApp('home'); /* navigates to the page we want to test */
    });

    it('Kibana Home view', async () => {
      await retry.waitFor(
        'home page visible',
        async () => await testSubjects.exists('homeApp')
      ); /* confirm you're on the correct page and that it's loaded */
      await a11y.testAppSnapshot(); /* this expects that there are no failures found by axe */
    });

    /**
     * If these tests were added by our QA team, tests that fail that require significant app code
     * changes to be fixed will be skipped with a corresponding issue label with more info
     */
    // Skipped due to https://github.com/elastic/kibana/issues/99999
    it.skip('all plugins view page meets a11y requirements', async () => {
      await home.clickAllKibanaPlugins();
      await a11y.testAppSnapshot();
    });

    /**
     * Testing all the versions and different views of of a page is important to get good
     * coverage. Things like empty states, different license levels, different permissions, and
     * loaded data can all significantly change the UI which necessitates their own test.
     */
    it('Add Kibana sample data page', async () => {
      await common.navigateToUrl('home', '/tutorial_directory/sampleData', {
        useActualUrl: true,
      });
      await a11y.testAppSnapshot();
    });
  });
}

1)    Dashboard
       create dashboard button:

      Error: a11y report:

 VIOLATION
   [aria-hidden-focus]: Ensures aria-hidden elements do not contain focusable elements
     Help: https://dequeuniversity.com/rules/axe/3.5/aria-hidden-focus?application=axeAPI
     Elements:
       - #example
       at Accessibility.testAxeReport (test/accessibility/services/a11y/a11y.ts:90:15)
       at Accessibility.testAppSnapshot (test/accessibility/services/a11y/a11y.ts:58:18)
       at process._tickCallback (internal/process/next_tick.js:68:7)

Packaging tests use Vagrant virtual machines as hosts and Ansible for provisioning and assertions. Kibana distributions are copied from the target folder into each VM and installed, along with required dependencies.

# Build distributions
node scripts/build --all-platforms --debug

cd test/package

# Setup virtual machine and networking
vagrant up <hostname> --no-provision

# Install Kibana and run OS level tests
# This step can be repeated when adding new tests, it ensures machine state - installations won't run twice
vagrant provision <hostname>

# Running functional tests
node scripts/es snapshot \
  -E network.bind_host=127.0.0.1,192.168.56.1 \
  -E discovery.type=single-node \
  --license=trial
TEST_KIBANA_URL=http://elastic:changeme@<ip>:5601 \
TEST_ES_URL=http://elastic:changeme@192.168.56.1:9200 \
  node scripts/functional_test_runner.js --include-tag=smoke

vagrant destroy <hostname>