.. | ||
common | ||
public | ||
server | ||
cypress.sh | ||
jest.config.js | ||
jest.sh | ||
kibana.json | ||
README.md | ||
tsconfig.json |
Enterprise Search
Overview
This plugin provides beta Kibana user interfaces for managing the Enterprise Search solution and its products, App Search and Workplace Search.
⚠️ The Kibana interface for Enterprise Search is a beta feature. It is subject to change and is not covered by the same level of support as generally available features. This interface will become the sole management panel for Enterprise Search with the 8.0 release. Until then, the standalone Enterprise Search UI remains available and supported.
App Search
![](/maxmustermann/kibana/media/commit/5e5dd074705f896804d2989c65612da8fc9da151/x-pack/plugins/enterprise_search/public/applications/enterprise_search/assets/app_search.png)
Add rich, relevant search to your apps and websites. https://www.elastic.co/app-search/
Workplace Search
![](/maxmustermann/kibana/media/commit/5e5dd074705f896804d2989c65612da8fc9da151/x-pack/plugins/enterprise_search/public/applications/enterprise_search/assets/workplace_search.png)
Unify all your team's content into a personalized search experience. https://www.elastic.co/workplace-search/
Development
- When developing locally, Enterprise Search should be running locally alongside Kibana on
localhost:3002
. - Update
config/kibana.dev.yml
withenterpriseSearch.host: 'http://localhost:3002'
Problems? If you're an Elastic Enterprise Search engineer, please reach out to @elastic/enterprise-search-frontend for questions or our in-depth Getting Started developer guide.
Don't forget to read Kibana's contributing documentation and developer guides for more general info on the Kibana ecosystem.
Kea
Enterprise Search uses Kea.js to manage our React/Redux state for us. Kea state is handled in our *Logic
files and exposes values and actions for our components to get and set state with.
Advanced Kea usage
For the most part, we stick to the functionality described in Kea's core concepts. However, in some files, we also take advantage of props and events, as well as manually mounting some shared logic files on plugin init outside of React.
Debugging Kea
To debug Kea state in-browser, Kea recommends Redux Devtools. To facilitate debugging, we use the path key with snake_case
d paths. The path key should always end with the logic filename (e.g. ['enterprise_search', 'some_logic']
) to make it easy for devs to quickly find/jump to files via IDE tooling.
Testing
Unit tests
Documentation: https://www.elastic.co/guide/en/kibana/current/development-tests.html#_unit_testing
Jest tests can be run directly from the x-pack/plugins/enterprise_search
folder. This also works for any subfolders or subcomponents.
yarn test:jest
yarn test:jest --watch
Unfortunately coverage collection does not work as automatically, and requires using our handy jest.sh script if you want to run tests on a specific file or folder and only get coverage numbers for that file or folder:
# Running the jest.sh script from the `x-pack/plugins/enterprise_search` folder (vs. kibana root)
# will save you time and allow you to Tab to complete folder dir names
sh jest.sh {YOUR_COMPONENT_DIR}
sh jest.sh public/applications/shared/kibana
sh jest.sh server/routes/app_search
# When testing an individual file, remember to pass the path of the test file, not the source file.
sh jest.sh public/applications/shared/flash_messages/flash_messages_logic.test.ts
E2E tests
We currently have two testing libraries in which we run E2E tests:
- Cypress
- Will contain the majority of our happy path E2E testing
- Kibana's Functional Test Runner (FTR)
- Contains basic tests that only run when the Enterprise Search host is not configured
- It's likely we will not continue to expand these tests, and might even trim some over time (to be replaced by Cypress)
Cypress tests
Documentation: https://docs.cypress.io/
Cypress tests can be run directly from the x-pack/plugins/enterprise_search
folder. You can use our handy cypress.sh script to run specific product test suites:
# Basic syntax
sh cypress.sh {run|open} {suite}
# Examples
sh cypress.sh run overview # run Enterprise Search overview tests
sh cypress.sh open overview # open Enterprise Search overview tests
sh cypress.sh run as # run App Search tests
sh cypress.sh open as # open App Search tests
sh cypress.sh run ws # run Workplace Search tests
sh cypress.sh open ws # open Workplace Search tests
# Overriding env variables
sh cypress.sh open as --env username=enterprise_search password=123
# Overriding config settings, e.g. changing the base URL to a dev path, or enabling video recording
sh cypress.sh open as --config baseUrl=http://localhost:5601/xyz video=true
# Only run a single specific test file
sh cypress.sh run ws --spec '**/example.spec.ts'
# Opt to run Chrome headlessly
sh cypress.sh run ws --headless
There are 3 ways you can spin up the required environments to run our Cypress tests:
- Running Cypress against local dev environments:
- Elasticsearch:
- Start a local instance, or use Kibana's
yarn es snapshot
command (with all configurations/versions required to run Enterprise Search locally) - NOTE: We generally recommend a fresh instance (or blowing away your
data/
folder) to reduce false negatives due to custom user data
- Start a local instance, or use Kibana's
- Kibana:
- You must have
csp.strict: false
andcsp.warnLegacyBrowsers: false
set in yourkibana.dev.yml
. - You should either start Kibana with
yarn start --no-base-path
or pass--config baseUrl=http://localhost:5601/xyz
into your Cypress command.
- You must have
- Enterprise Search:
- Nothing extra is required to run Cypress tests, only what is already needed to run Kibana/Enterprise Search locally.
- Elasticsearch:
- Running Cypress against Kibana's functional test server:
- ℹ️ While we won't use the runner, we can still make use of Kibana's functional test server to help us spin up Elasticsearch and Kibana instances.
- NOTE: We recommend stopping any other local dev processes, to reduce issues with memory/performance
- From the
x-pack/
project folder, runnode scripts/functional_tests_server --config test/functional_enterprise_search/cypress.config.ts
- Kibana:
- You will need to pass
--config baseUrl=http://localhost:5620
into your Cypress command.
- You will need to pass
- Enterprise Search:
- ⚠️ TODO: We currently do not have a way of spinning up Enterprise Search from Kibana's FTR - for now, you can use local Enterprise Search (pointed at the FTR's
http://localhost:9220
Elasticsearch host instance)
- ⚠️ TODO: We currently do not have a way of spinning up Enterprise Search from Kibana's FTR - for now, you can use local Enterprise Search (pointed at the FTR's
- ℹ️ While we won't use the runner, we can still make use of Kibana's functional test server to help us spin up Elasticsearch and Kibana instances.
- Running Cypress against Enterprise Search dockerized stack scripts
- ⚠️ This is for Enterprise Search devs only, as this requires access to our closed source Enterprise Search repo
stack_scripts/start-with-es-native-auth.sh --with-kibana
- Note that the tradeoff of an easier one-command start experience is you will not be able to run Cypress tests against any local changes.
Debugging
Cypress can either run silently in a headless browser in the command line (run
or --headless
mode), which is the default mode used by CI, or opened interactively in an included app and the Chrome browser (open
or --headed --no-exit
mode).
For debugging failures locally, we generally recommend using open mode, which allows you to run a single specific test suite, and makes browser dev tools available to you so you can pause and inspect DOM as needed.
⚠️ Although this is more extra caution than a hard-and-fast rule, we generally recommend taking a break and not clicking or continuing to use the app while tests are running. This can eliminate or lower the possibility of hard-to-reproduce/intermittently flaky behavior and timeouts due to user interference.
Artifacts
All failed tests will output a screenshot to the x-pack/plugins/enterprise_search/target/cypress/screenshots
folder. We strongly recommend starting there for debugging failed tests to inspect error messages and UI state at point of failure.
To track what Cypress is doing while running tests, you can pass in --config video=true
which will output screencaptures to a videos/
folder for all tests (both successful and failing). This can potentially provide more context leading up to the failure point, if a static screenshot isn't providing enough information.
ℹ️ We have videos turned off in our config to reduce test runtime, especially on CI, but suggest re-enabling it for any deep debugging.
Kibana FTR tests
See our functional test runner README.
Our automated accessibility tests can be found in x-pack/test/accessibility/apps.