Skip to content

Latest commit

 

History

History
140 lines (90 loc) · 8.1 KB

README.md

File metadata and controls

140 lines (90 loc) · 8.1 KB
Raw

Enterprise Search

Overview

This plugin provides Kibana user interfaces for managing the Enterprise Search solution and its products, App Search and Workplace Search.

App Search

Add rich, relevant search to your apps and websites. https://www.elastic.co/app-search/

Workplace Search

Unify all your team's content into a personalized search experience. https://www.elastic.co/workplace-search/

Development

  1. When developing locally, Enterprise Search should be running locally alongside Kibana on localhost:3002.
  2. Update config/kibana.dev.yml with enterpriseSearch.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.

Server development

Kibana runs both a frontend and a backend/middleware server. For server development guidelines, see SERVER.md.

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.

For extended guidelines, please check KEA.md

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_cased 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 from the root kibana directory, however, since the tests take so long to run you will likely want to apply the appropriate Jest configuration file to test only your changes. For example:

  • x-pack/plugins/enterprise_search/common/jest.config.js
  • x-pack/plugins/enterprise_search/public/jest.config.js
  • x-pack/plugins/enterprise_search/server/jest.config.js
yarn test:jest --config {YOUR_JEST_CONFIG_FILE}
yarn test:jest --config {YOUR_JEST_CONFIG_FILE} --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|dev}

# Examples
sh cypress.sh run    # run Enterprise Search tests
sh cypress.sh open   # open Enterprise Search tests
sh cypress.sh dev    # run "cypress only" with Enterprise Search config

There are 3 ways you can spin up the required environments to run our Cypress tests:

  1. 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
    • Kibana:
      • You must have csp.strict: false and csp.warnLegacyBrowsers: false set in your kibana.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.
    • Enterprise Search:
      • Nothing extra is required to run Cypress tests, only what is already needed to run Kibana/Enterprise Search locally.
  2. Running Cypress against Kibana's functional test server:
    • Make sure docker is up and running in you system
    • From the x-pack/ project folder, run sh cypress.sh which will spin up Kibana, Elasticsearch through functional test runners and Enterprise Search instance in Docker.
  3. 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.