kibana/x-pack

Elastic License Functionality

This directory tree contains files subject to the Elastic License. The files subject to the Elastic License are grouped in this directory to clearly separate them from files licensed under the Apache License 2.0.

Development

By default, Kibana will run with X-Pack installed as mentioned in the contributing guide.

Elasticsearch will run with a basic license. To run with a trial license, including security, you can specifying that with the yarn es command.

Example: yarn es snapshot --license trial --password changeme

Testing

Running unit tests_bundle

You can run unit tests by running:

yarn test

If you want to run tests only for a specific plugin (to save some time), you can run:

yarn test --plugins <plugin>[,<plugin>]*    # where <plugin> is "reporting", etc.

Running single test file

Edit test file, changing top level describe to describe.only. Run tests with normal commands.

Debugging browser tests

yarn test:browser:dev

Initializes an environment for debugging the browser tests. Includes an dedicated instance of the kibana server for building the test bundle, and a karma server. When running this task the build is optimized for the first time and then a karma-owned instance of the browser is opened. Click the "debug" button to open a new tab that executes the unit tests.

Run single tests by appending grep parameter to the end of the URL. For example http://localhost:9876/debug.html?grep=ML%20-%20Explorer%20Controller will only run tests with 'ML - Explorer Controller' in the describe block.

Running server unit tests

You can run server-side unit tests by running:

yarn test:server

Running functional tests

The functional tests are run against a live browser, Kibana, and Elasticsearch install. They build their own version of elasticsearch and x-pack-elasticsearch, run the builds automatically, startup the kibana server, and run the tests against them.

To do all of this in a single command run:

node scripts/functional_tests

If you are developing functional tests then you probably don't want to rebuild elasticsearch and wait for all that setup on every test run, so instead use this command to get started:

node scripts/functional_tests_server

After both Elasticsearch and Kibana are running, open a new terminal (without tearing down Elasticsearch, Kibana, etc.) and use the following to run the tests:

# this command accepts a bunch of arguments to tweak the run, try sending --help to learn more
node ../scripts/functional_test_runner

Running API integration tests

API integration tests are very similar to functional tests in a sense that they are organized in the same way and run against live Kibana and Elasticsearch instances. The difference is that API integration tests are intended to test only programmatic API exposed by Kibana. There is no need to run browser and simulate user actions that significantly reduces execution time.

To build, run x-pack-kibana with x-pack-elasticsearch and then run API integration tests against them use the following command:

node scripts/functional_tests_api

If you are developing api integration tests then you probably don't want to rebuild x-pack-elasticsearch and wait for all that setup on every test run, so instead use this command to get started:

node scripts/functional_tests_server

Once Kibana and Elasticsearch are up and running open a new terminal and run this command to just run the tests (without tearing down Elasticsearch, Kibana, etc.)

# this command accepts a bunch of arguments to tweak the run, try sending --help to learn more
node ../scripts/functional_test_runner --config test/api_integration/config.js

You can also run API integration tests with SAML support. The --saml option configures both Kibana and Elasticsearch with the SAML security realm, as required by the SAML security API.

Start the functional test server with SAML support:

node scripts/functional_tests_server --saml

Then run the tests with:

# make sure you are in the x-pack-kibana project
cd x-pack-kibana

# use a different config for SAML
node ../scripts/functional_test_runner --config test/saml_api_integration/config.js

Issues starting dev more of creating builds

You may see an error like this when you are getting started:

[14:08:15] Error: Linux x86 checksum failed
    at download_phantom.js:42:15
    at process._tickDomainCallback (node.js:407:9)

That's thanks to the binary Phantom downloads that have to happen, and Bitbucket being annoying with throttling and redirecting or... something. The real issue eludes me, but you have 2 options to resolve it.

1. Just keep re-running the command until it passes. Eventually the downloads will work, and since they are cached, it won't ever be an issue again.
2. Download them by hand from Bitbucket and copy them into the .phantom path. We're currently using 1.9.8, and you'll need the Window, Mac, and Linux builds. <<<<<<< HEAD

Building and Packaging

Make sure you have the dependencies installed by running yarn kbn bootstrap.

Once complete, use yarn build. Output will be placed in the build path (it will be created).

To drop the SNAPSHOT off the version, use the release flag, -r or --release

If you'd like to get a zip package and a sha1 checksum file, use yarn package. Output will be placed in the target path (it will be created). Resulting build output will also be left in the build path.

Releasing

Make sure you have the dependencies installed by running yarn kbn bootstrap.

Once complete, use yarn release. Build and package output will be placed in the build and target paths respectively (they will be created).

Note that you will need AWS credentials for the upload to succeed. To provide these credentials, create a ~/.aws/credentials file with your credentials, which should look like this:

[default] ; the default profile
aws_access_key_id = ...
aws_secret_access_key = ...

[another-config] ; my "personal-account" profile
aws_access_key_id = ...
aws_secret_access_key = ...

The default profile is used automatically, but setting the AWS_PROFILE environment variable will allow you to use another profile, if you happen to have multiple.

AWS_PROFILE=another-config yarn release

See the AWS docs for more information.

Building documentation

This repo contains X-Pack information that is used in the Kibana User Guide in 5.5 and later.

To build the Kibana User Guide on your local machine, ensure you have the following folders:

$ ls $PATH_TO_REPOS
 ├── kibana
 └── kibana-extra/x-pack-kibana

To build the Kibana User Guide, use the docbldkb or docbldkbx build commands defined in https://github.com/elastic/docs/blob/master/doc_build_aliases.sh

Updates to contributing guide and defaults (#13)