From d03910d6d2d20467bc7c76026b6c9f8f4a68860e Mon Sep 17 00:00:00 2001 From: Mihir Soni Date: Thu, 11 Mar 2021 19:43:09 -0800 Subject: [PATCH] [Rename] Refactored src/{typings,test_helpers,utils} root files (#140) * [Rename] src/core/test_helpers * [Rename] src/core/types * [Rename] src/core/utils * [Rename] src/core/ docs Signed-off-by: Mihir Soni --- src/core/CONVENTIONS.md | 12 +- src/core/README.md | 30 ++--- src/core/TESTING.md | 96 +++++++-------- .../{kbn_server.ts => osd_server.ts} | 110 +++++++++--------- src/core/types/capabilities.ts | 2 +- src/core/types/saved_objects.ts | 2 +- src/core/types/ui_settings.ts | 2 +- src/core/utils/context.ts | 4 +- src/core/utils/default_app_categories.ts | 10 +- 9 files changed, 134 insertions(+), 134 deletions(-) rename src/core/test_helpers/{kbn_server.ts => osd_server.ts} (70%) diff --git a/src/core/CONVENTIONS.md b/src/core/CONVENTIONS.md index a4f50e73f1c5..39bf54e09268 100644 --- a/src/core/CONVENTIONS.md +++ b/src/core/CONVENTIONS.md @@ -21,7 +21,7 @@ Definition of done for a feature: - there is no contradiction between client and server API - works for OSS version - works with and without a `server.basePath` configured - - cannot crash the Kibana server when it fails + - cannot crash the OpenSearch Dashboards server when it fails - works for the commercial version with a license - for a logged-in user - for anonymous user @@ -37,11 +37,11 @@ Definition of done for a feature: ## Technical Conventions ### Plugin Structure -All Kibana plugins built at Elastic should follow the same structure. +All OpenSearch Dashboards plugins built at Elastic should follow the same structure. ``` my_plugin/ -├── kibana.json +├── opensearch_dashboards.json ├── public │   ├── applications │   │   ├── my_app @@ -68,7 +68,7 @@ my_plugin/    ├── index.ts    └── plugin.ts ``` -- [Manifest file](/docs/development/core/server/kibana-plugin-core-server.pluginmanifest.md) should be defined on top level. +- [Manifest file](/docs/development/core/server/opensearch-dashboards-plugin-core-server.pluginmanifest.md) should be defined on top level. - Both `server` and `public` should have an `index.ts` and a `plugin.ts` file: - `index.ts` should only contain: - The `plugin` export @@ -293,7 +293,7 @@ For creating and registering a Usage Collector. Collectors should be defined in ```ts // server/collectors/register.ts import { UsageCollectionSetup } from 'src/plugins/usage_collection/server'; -import { CallCluster } from 'src/legacy/core_plugins/elasticsearch'; +import { CallCluster } from 'src/legacy/core_plugins/opensearch'; export function registerMyPluginUsageCollector(usageCollection?: UsageCollectionSetup): void { // usageCollection is an optional dependency, so make sure to return if it is not registered. @@ -306,7 +306,7 @@ export function registerMyPluginUsageCollector(usageCollection?: UsageCollection type: MY_USAGE_TYPE, fetch: async (callCluster: CallCluster) => { - // query ES and get some data + // query OpenSearch and get some data // summarize the data into a model // return the modeled object that includes whatever you want to track diff --git a/src/core/README.md b/src/core/README.md index e195bf30c054..f38b9b49db86 100644 --- a/src/core/README.md +++ b/src/core/README.md @@ -1,35 +1,35 @@ # Core -Core is a set of systems (frontend, backend etc.) that Kibana and its plugins are built on top of. +Core is a set of systems (frontend, backend etc.) that OpenSearch Dashboards and its plugins are built on top of. ## Plugin development Core Plugin API Documentation: - - [Core Public API](/docs/development/core/public/kibana-plugin-core-public.md) - - [Core Server API](/docs/development/core/server/kibana-plugin-core-server.md) + - [Core Public API](/docs/development/core/public/opensearch-dashboards-plugin-core-public.md) + - [Core Server API](/docs/development/core/server/opensearch-dashboards-plugin-core-server.md) - [Conventions for Plugins](./CONVENTIONS.md) - - [Testing Kibana Plugins](./TESTING.md) - - [Kibana Platform Plugin API](./docs/developer/architecture/kibana-platform-plugin-api.asciidoc ) + - [Testing OpenSearch Dashboards Plugins](./TESTING.md) + - [OpenSearch Dashboards Platform Plugin API](./docs/developer/architecture/kibana-platform-plugin-api.asciidoc ) Internal Documentation: - [Saved Objects Migrations](./server/saved_objects/migrations/README.md) -## Integration with the "legacy" Kibana +## Integration with the "legacy" OpenSearch Dashboards -Most of the existing core functionality is still spread over "legacy" Kibana and it will take some time to upgrade it. -Kibana is started using existing "legacy" CLI that bootstraps `core` which in turn creates the "legacy" Kibana server. -At the moment `core` manages HTTP connections, handles TLS configuration and base path proxy. All requests to Kibana server +Most of the existing core functionality is still spread over "legacy" OpenSearch Dashboards and it will take some time to upgrade it. +OpenSearch Dashboards is started using existing "legacy" CLI that bootstraps `core` which in turn creates the "legacy" OpenSearch Dashboards server. +At the moment `core` manages HTTP connections, handles TLS configuration and base path proxy. All requests to OpenSearch Dashboards server will hit HTTP server exposed by the `core` first and it will decide whether request can be solely handled by the new -platform or request should be proxied to the "legacy" Kibana. This setup allows `core` to gradually introduce any "pre-route" -processing logic, expose new routes or replace old ones handled by the "legacy" Kibana currently. +platform or request should be proxied to the "legacy" OpenSearch Dashboards. This setup allows `core` to gradually introduce any "pre-route" +processing logic, expose new routes or replace old ones handled by the "legacy" OpenSearch Dashboards currently. -Once config has been loaded and some of its parts were validated by the `core` it's passed to the "legacy" Kibana where +Once config has been loaded and some of its parts were validated by the `core` it's passed to the "legacy" OpenSearch Dashboards where it will be additionally validated so that we can make config validation stricter with the new config validation system. Even though the new validation system provided by the `core` is also based on Joi internally it is complemented with custom rules tailored to our needs (e.g. `byteSize`, `duration` etc.). That means that config values that were previously accepted -by the "legacy" Kibana may be rejected by the `core` now. +by the "legacy" OpenSearch Dashboards may be rejected by the `core` now. Even though `core` has its own logging system it doesn't output log records directly (e.g. to file or terminal), but instead -forward them to the "legacy" Kibana so that they look the same as the rest of the log records throughout Kibana. +forward them to the "legacy" OpenSearch Dashboards so that they look the same as the rest of the log records throughout OpenSearch Dashboards. ## Core API Review To provide a stable API for plugin developers, it is important that the Core Public and Server API's are stable and @@ -39,7 +39,7 @@ process described below. Changes to the API signature which have not been accept When changes to the Core API's signatures are made, the following process needs to be followed: 1. After changes have been made, run `yarn docs:acceptApiChanges` which performs the following: - Recompiles all typescript typings files - - Updates the API review files `src/core/public/kibana.api.md` and `src/core/server/kibana.api.md` + - Updates the API review files `src/core/public/opensearch_dashboards.api.md` and `src/core/server/opensearch_dashboards.api.md` - Updates the Core API documentation in `docs/development/core/` 2. Review and commit the updated API Review files and documentation 3. Clearly flag any breaking changes in your pull request diff --git a/src/core/TESTING.md b/src/core/TESTING.md index 0ae759f78c93..7c1c6f20fef8 100644 --- a/src/core/TESTING.md +++ b/src/core/TESTING.md @@ -1,10 +1,10 @@ -# Testing Kibana Plugins +# Testing OpenSearch Dashboards Plugins -This document outlines best practices and patterns for testing Kibana Plugins. +This document outlines best practices and patterns for testing OpenSearch Dashboards Plugins. -- [Testing Kibana Plugins](#testing-kibana-plugins) +- [Testing OpenSearch Dashboards Plugins](#testing-opensearch-dashboards-plugins) - [Strategy](#strategy) - - [New concerns in the Kibana Platform](#new-concerns-in-the-kibana-platform) + - [New concerns in the OpenSearch Dashboards Platform](#new-concerns-in-the-opensearch-dashboards-platform) - [Core Integrations](#core-integrations) - [Core Mocks](#core-mocks) - [Example](#example) @@ -23,7 +23,7 @@ This document outlines best practices and patterns for testing Kibana Plugins. - [SavedObjects](#savedobjects) - [Unit Tests](#unit-tests) - [Integration Tests](#integration-tests-1) - - [Elasticsearch](#elasticsearch) + - [OpenSearch](#opensearch) - [Plugin integrations](#plugin-integrations) - [Preconditions](#preconditions-1) - [Testing dependencies usages](#testing-dependencies-usages) @@ -35,20 +35,20 @@ This document outlines best practices and patterns for testing Kibana Plugins. In general, we recommend three tiers of tests: - Unit tests: small, fast, exhaustive, make heavy use of mocks for external dependencies -- Integration tests: higher-level tests that verify interactions between systems (eg. HTTP APIs, Elasticsearch API calls, calling other plugin contracts). +- Integration tests: higher-level tests that verify interactions between systems (eg. HTTP APIs, OpenSearch API calls, calling other plugin contracts). - End-to-end tests (e2e): tests that verify user-facing behavior through the browser These tiers should roughly follow the traditional ["testing pyramid"](https://martinfowler.com/articles/practical-test-pyramid.html), where there are more exhaustive testing at the unit level, fewer at the integration level, and very few at the functional level. -## New concerns in the Kibana Platform +## New concerns in the OpenSearch Dashboards Platform -The Kibana Platform introduces new concepts that legacy plugins did not have concern themselves with. Namely: +The OpenSearch Dashboards Platform introduces new concepts that legacy plugins did not have concern themselves with. Namely: - **Lifecycles**: plugins now have explicit lifecycle methods that must interop with Core APIs and other plugins. - **Shared runtime**: plugins now all run in the same process at the same time. On the frontend, this is different behavior than the legacy plugins. Developers should take care not to break other plugins when interacting with their enviornment (Node.js or Browser). -- **Single page application**: Kibana's frontend is now a single-page application where all plugins are running, but only one application is mounted at a time. Plugins need to handle mounting and unmounting, cleanup, and avoid overriding global browser behaviors in this shared space. +- **Single page application**: OpenSearch Dashboards's frontend is now a single-page application where all plugins are running, but only one application is mounted at a time. Plugins need to handle mounting and unmounting, cleanup, and avoid overriding global browser behaviors in this shared space. - **Dependency management**: plugins must now explicitly declare their dependencies on other plugins, both required and optional. Plugins should ensure to test conditions where a optional dependency is missing. -Simply porting over existing tests when migrating your plugin to the Kibana Platform will leave blind spots in test coverage. It is highly recommended that plugins add new tests that cover these new concerns. +Simply porting over existing tests when migrating your plugin to the OpenSearch Dashboards Platform will leave blind spots in test coverage. It is highly recommended that plugins add new tests that cover these new concerns. ## Core Integrations @@ -61,18 +61,18 @@ If the unit under test expects a particular response from a Core API, the test w #### Example ```typescript -import { elasticsearchServiceMock } from 'src/core/server/mocks'; +import { opensearchServiceMock } from 'src/core/server/mocks'; test('my test', async () => { // Setup mock and faked response - const esClient = elasticsearchServiceMock.createScopedClusterClient(); - esClient.callAsCurrentUser.mockResolvedValue(/** insert ES response here */); + const opensearchClient = opensearchServiceMock.createScopedClusterClient(); + opensearchClient.callAsCurrentUser.mockResolvedValue(/** insert OpenSearch response here */); // Call unit under test with mocked client - const result = await myFunction(esClient); + const result = await myFunction(opensearchClient); // Assert that client was called with expected arguments - expect(esClient.callAsCurrentUser).toHaveBeenCalledWith(/** expected args */); + expect(opensearchClient.callAsCurrentUser).toHaveBeenCalledWith(/** expected args */); // Expect that unit under test returns expected value based on client's response expect(result).toEqual(/** expected return value */) }); @@ -81,8 +81,8 @@ test('my test', async () => { ## Strategies for specific Core APIs ### HTTP Routes -The HTTP API interface is another public contract of Kibana, although not every Kibana endpoint is for external use. When evaluating the required level of test coverage for an HTTP resource, make your judgment based on whether an endpoint is considered to be public or private. Public API is expected to have a higher level of test coverage. -Public API tests should cover the **observable behavior** of the system, therefore they should be close to the real user interactions as much as possible, ideally by using HTTP requests to communicate with the Kibana server as a real user would do. +The HTTP API interface is another public contract of OpenSearch Dashboards, although not every OpenSearch Dashboards endpoint is for external use. When evaluating the required level of test coverage for an HTTP resource, make your judgment based on whether an endpoint is considered to be public or private. Public API is expected to have a higher level of test coverage. +Public API tests should cover the **observable behavior** of the system, therefore they should be close to the real user interactions as much as possible, ideally by using HTTP requests to communicate with the OpenSearch Dashboards server as a real user would do. ##### Preconditions We are going to add tests for `myPlugin` plugin that allows to format user-provided text, store and retrieve it later. @@ -232,8 +232,8 @@ Main subjects for tests should be: - dependencies on other plugins. ##### Functional Test Runner -If your plugin relies on the elasticsearch server to store data and supports additional configuration, you can leverage the Functional Test Runner(FTR) to implement integration tests. -FTR bootstraps an elasticsearch and a Kibana instance and runs the test suite against it. +If your plugin relies on the opensearch server to store data and supports additional configuration, you can leverage the Functional Test Runner(FTR) to implement integration tests. +FTR bootstraps an opensearch and a OpenSearch Dashboards instance and runs the test suite against it. Pros: - runs the whole Elastic stack - tests cross-plugin integration @@ -246,12 +246,12 @@ Cons: - brittle tests ###### Example -You can reuse existing [api_integration](/test/api_integration/config.js) setup by registering a test file within a [test loader](/test/api_integration/apis/index.js). More about the existing FTR setup in the [contribution guide](/CONTRIBUTING.md#running-specific-kibana-tests) +You can reuse existing [api_integration](/test/api_integration/config.js) setup by registering a test file within a [test loader](/test/api_integration/apis/index.js). More about the existing FTR setup in the [contribution guide](/CONTRIBUTING.md#running-specific-opensearch-dashboards-tests) The tests cover: - authenticated / non-authenticated user access (when applicable) ```typescript -// TODO after https://github.com/elastic/kibana/pull/53208/ +// TODO after https://github.com/elastic/opensearch-dashboards/pull/53208/ ``` - request validation ```typescript @@ -307,36 +307,36 @@ export default function({ getService }: FtrProviderContext) { ``` ##### TestUtils -It can be utilized if your plugin doesn't interact with the elasticsearch server or mocks the own methods doing so. -Runs tests against real Kibana server instance. +It can be utilized if your plugin doesn't interact with the opensearch server or mocks the own methods doing so. +Runs tests against real OpenSearch Dashboards server instance. Pros: -- runs the real Kibana instance +- runs the real OpenSearch Dashboards instance - tests cross-plugin integration - emulates a real user interaction with the HTTP resources Cons: -- faster than FTR because it doesn't run elasticsearch instance, but still slow +- faster than FTR because it doesn't run opensearch instance, but still slow - hard to debug -- doesn't cover Kibana CLI logic +- doesn't cover OpenSearch Dashboards CLI logic ###### Example -To have access to Kibana TestUtils, you should create `integration_tests` folder and import `test_utils` within a test file: +To have access to OpenSearch Dashboards TestUtils, you should create `integration_tests` folder and import `test_utils` within a test file: ```typescript // src/plugins/my_plugin/server/integration_tests/formatter.test.ts -import * as kbnTestServer from 'src/core/test_helpers/kbn_server'; +import * as osdTestServer from 'src/core/test_helpers/osd_server'; describe('myPlugin', () => { describe('GET /myPlugin/formatter', () => { - let root: ReturnType; + let root: ReturnType; beforeAll(async () => { - root = kbnTestServer.createRoot(); + root = osdTestServer.createRoot(); await root.setup(); await root.start(); }, 30000); afterAll(async () => await root.shutdown()); it('validates given text', async () => { - const response = await kbnTestServer.request + const response = await osdTestServer.request .get(root, '/myPlugin/formatter') .query({ text: 'input string'.repeat(100) }) .expect(400); @@ -345,7 +345,7 @@ describe('myPlugin', () => { }); it('formats given text', async () => { - const response = await kbnTestServer.request + const response = await osdTestServer.request .get(root, '/myPlugin/formatter') .query({ text: 'input string' }) .expect(200); @@ -354,7 +354,7 @@ describe('myPlugin', () => { }); it('returns BadRequest if passed string contains banned symbols', async () => { - await kbnTestServer.request + await osdTestServer.request .get(root, '/myPlugin/formatter') .query({ text: '