diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fd8427401..01048f2d7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,12 +1,4 @@ - [Contributing to OpenSearch](#contributing-to-opensearch) -- [Developer Guide](#developer-guide) - - [Install Dependencies](#install-dependencies) - - [opensearch-dashboards-test-library](#opensearch-dashboards-test-library) - - [Run Tests](#run-tests) - - [Formatting](#formatting) - - [Onboarding](#onboarding) - - [Test Development](#test-development) - - [Experimental Features](#experimental-features) - [Release](#release) - [First Things First](#first-things-first) - [Ways to Contribute](#ways-to-contribute) @@ -25,161 +17,6 @@ OpenSearch is a community project that is built and maintained by people just like **you**. We're glad you're interested in helping out. There are several different ways you can do it, but before we talk about that, let's talk about how to get started. -## Developer Guide - -### Install Dependencies - -#### opensearch-dashboards-test-library - -opensearch-dashboards-test-library is the test utility library used by this project, it is already a published package in NPM. You can import the lastest version by installing from NPM registry - -``` -"@opensearch-dashboards-test/opensearch-dashboards-test-library": "^1.0.1" -``` - -You can also import from the git repository target branch to use the development code directly - -``` -"@opensearch-dashboards-test/opensearch-dashboards-test-library": "opensearch-project/opensearch-dashboards-test-library#main" -``` - -You need to delete the package from the node_modules folder and run npm install again, to reflect the change. - -``` -$ npm uninstall @opensearch-dashboards-test/opensearch-dashboards-test-library && npm install opensearch-project/opensearch-dashboards-test-library#main -``` - -### Run Tests - -You can run the cypress tests by cli. There are some handy scripts in [package.json](package.json) to run the tests with some pre-set configurations. - -To run tests against a local cluster - -without security: - -``` -$ yarn cypress run-without-security --spec "cypress/integration/core-opensearch-dashboards/vanilla-opensearch-dashboards/*.js" -``` - -with security: - -``` -$ yarn cypress run-with-security --spec "cypress/integration/core-opensearch-dashboards/opensearch-dashboards/*.js" -``` - -These tests run in headless mode by default. You can also manually trigger the test via browser UI by running: - -``` -$ yarn cypress open -``` - -And you can override certain [cypress config or environment variable](cypress.json) by applying additional cli arguments, for example to override the baseUrl and openSearchUrl to test a remote OpenSearch endpoint: - -``` -$ yarn cypress run --spec "cypress/integration/core-opensearch-dashboards/opensearch-dashboards/*.js" --config "baseUrl=https:///_dashboards" --env "openSearchUrl=https://,SECURITY_ENABLED=true,username=admin,password=xxxxxxxx,ENDPOINT_WITH_PROXY=true" -``` - -`SECURITY_ENABLED`: if true, the `username` and `password` passing in are used as basic authentication credentials during `cy.visit` and `cy.request`. Also, please notice security enabled endpoint normally uses https protocol, so you may want to pass in different urls. - -`ENDPOINT_WITH_PROXY`: for an OpenSearch endpoint wrapped with a proxy that redirects the visiting url to the login url, even with auth option provided in `cy.visit`, the redirection to the login url still happens. So a login request before tests and cache the security cookie are needed and can be switched on by this argument. - -`MANAGED_SERVICE_ENDPOINT`: set to true if tests are running against managed service domains. - -### Formatting - -`prettier` and `ESLint` is integrated and used to standardize formatting of files, where `prettier` takes care of the code formatting and `ESLint` takes care of the code style. You can check the formatting of all files (new and existing) by running - -``` -$ yarn lint -``` -and auto fix the formatting of all files (new and existing) by running -``` -$ yarn lint --fix -``` - -`Husky` precommit hook is used to automatically run `yarn lint`, please fix the files according to lint result before commiting code changes (run `yarn lint --fix` for fixable errors, or manully fix code according to error messages). If you have any doubts on `ESLint` rules, feel free to [open an issue](issues). - -### Onboarding - -To onboard your release tests (Dashboards plugins) onto this repo test function, you can follow the next steps. - -0. Create a name to identify your plugin, e.g `plugin-name` - -The dir name shall be descriptive to identify your plugin. You can use the same name defined in build repo https://github.com/opensearch-project/opensearch-build/tree/main/scripts/components - -1. Place test files under `cypress/integration/plugins/` - -2. Place fixtures under `cypress/fixtures/plugins/` - -3. Place custom commands under `cypress/utils/plugins/`, if it's a general command that could be reused by other plugins, place it under `cypress/utils/commands.js` - -4. Place custom constants under `cypress/utils/plugins/`, reuse the constants in `cypress/utils/base_constants.js` - -5. Run tests - -Start OpenSearch and OpenSearch Dashboards. Then refer to the [test execution file](/integtest.sh). - -E.g if you want to run all plugin tests with security enabled. - -``` -npx cypress run --env SECURITY_ENABLED=true --spec "cypress/integration/plugins/*/*" -``` - -E.g if you want to run AD plugin tests with security enabled. - -``` -npx cypress run --env SECURITY_ENABLED=true --spec "cypress/integration/plugins/anomaly-detection-dashboards-plugin" -``` - -For the complete ways to run Cypress, you can refer to the Cypress official site https://docs.cypress.io/guides/getting-started/.installing-cypress#Opening-Cypress. - -The env parameters are defined in https://github.com/opensearch-project/opensearch-dashboards-functional-test/blob/main/cypress.json where you can look for or add the desired parameters. You can refer to the Cypress official site https://docs.cypress.io/guides/guides/environment-variables#Setting. - -6. [optional] Remove copied tests from your plugin and execute them remotely from your plugin - -Since your release tests have been moved in this repo, to avoid maintain duplicated code and potentially diverged Cypress versions in two repos, you can remove them from your plugin. Then execute the tests inside this repo from your CI. See AD's example https://github.com/opensearch-project/anomaly-detection-dashboards-plugin/blob/main/.github/workflows/remote-integ-tests-workflow.yml However, this can be decided at plugin level to phase out the changes. - -7. [optional] Verify test execution from OpenSearch build repo - -The tests inside this repo will be executed from OpenSearch build repo. You can verify that by running test script from https://github.com/opensearch-project/opensearch-build/tree/main/src/test_workflow Please refer to the repo to the way of test exeuction. Below is the set of commands you can use based on current situation. - -Suppose your plugin is ready for version 1.2.0 - -``` -./build.sh manifests/1.2.0/opensearch-1.2.0.yml - -./build.sh manifests/1.2.0/opensearch-dashboards-1.2.0.yml - -./assemble.sh builds/opensearch/manifest.yml - -./assemble.sh builds/opensearch-dashboards/manifest.yml - -./test.sh integ-test manifests/1.2.0/opensearch-dashboards-1.2.0-test.yml - -``` - -### Test Development - -#### Experimental Features - -When writing tests for experimental features, please follow these steps. - -1. Figure out the folder location to put the tests - -Similar to the regular tests, OSD Core tests go to the [folder](integration/core-opensearch-dashboards/opensearch-dashboards/) and OSD plugin tests go to the [folder](cypress/integration/plugins/). - -2. Develop tests with a flag to turn on and off - -Add an environment variable (e.g boolean) to only run tests for the experiemental feature when it is true. (Define such in [cypress configuration](cypress.json). Refer to `SECURITY_ENABLED` as an example) This is to ensure backward compatibility when integrating with [opensearch-build repo](https://github.com/opensearch-project/opensearch-build/blob/main/src/test_workflow/integ_test/service_opensearch_dashboards.py) whose OpenSearch Dashboards execution command or yml configuration may not be updated to support the experimental feature yet. - -3. Set up Github action to run the tests inside the current repo - -Create a new workflow by referring to [this template](https://github.com/opensearch-project/opensearch-dashboards-functional-test/blob/main/.github/workflows/release-e2e-workflow-template.yml) for OSD plugin or [this workflow](https://github.com/opensearch-project/opensearch-dashboards-functional-test/blob/main/.github/workflows/cypress-workflow-vanilla-snapshot-based.yml) for OSD Core. This workflow is to run the OSD from artifact. You could enable your experimental feature through either `./bin/opensearch-dashboards --vis_builder.enabled` or through modifying the content of the yml file. (In order to run the tests from the source code repo of the feature, you can set up workflows to check out the source code and use `yarn` to start OSD.) - -4. Run tests from `opensearch-build` - -To make the build repo enable your experimental feature when spinning up OSD service, make sure that you update [this file](https://github.com/opensearch-project/opensearch-build/blob/main/src/test_workflow/integ_test/service_opensearch_dashboards.py) You could either modify the start command or the yml file. To avoid a potentially long start command, it is preferred to modify the yml file to turn on the feature. - ## Release This project follows [OpenSearch project branching, labelling, and releasing](https://github.com/opensearch-project/.github/blob/main/RELEASING.md#opensearch-branching) to track 3 releases in parallel. diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md new file mode 100644 index 000000000..e401acec8 --- /dev/null +++ b/DEVELOPER_GUIDE.md @@ -0,0 +1,104 @@ +- [Developer Guide](#developer-guide) + - [Install Dependencies](#install-dependencies) + - [opensearch-dashboards-test-library](#opensearch-dashboards-test-library) + - [Run Tests](#run-tests) + - [Formatting](#formatting) + - [Test Development](#test-development) + - [Experimental Features](#experimental-features) + +## Developer Guide + +### Install Dependencies + +#### opensearch-dashboards-test-library + +opensearch-dashboards-test-library is the test utility library used by this project, it is already a published package in NPM. You can import the lastest version by installing from NPM registry + +``` +"@opensearch-dashboards-test/opensearch-dashboards-test-library": "^1.0.1" +``` + +You can also import from the git repository target branch to use the development code directly + +``` +"@opensearch-dashboards-test/opensearch-dashboards-test-library": "opensearch-project/opensearch-dashboards-test-library#main" +``` + +You need to delete the package from the node_modules folder and run npm install again, to reflect the change. + +``` +$ npm uninstall @opensearch-dashboards-test/opensearch-dashboards-test-library && npm install opensearch-project/opensearch-dashboards-test-library#main +``` + +### Run Tests + +You can run the cypress tests by cli. There are some handy scripts in [package.json](package.json) to run the tests with some pre-set configurations. + +To run tests against a local cluster + +without security: + +``` +$ yarn cypress run-without-security --spec "cypress/integration/core-opensearch-dashboards/vanilla-opensearch-dashboards/*.js" +``` + +with security: + +``` +$ yarn cypress run-with-security --spec "cypress/integration/core-opensearch-dashboards/opensearch-dashboards/*.js" +``` + +These tests run in headless mode by default. You can also manually trigger the test via browser UI by running: + +``` +$ yarn cypress open +``` + +And you can override certain [cypress config or environment variable](cypress.json) by applying additional cli arguments, for example to override the baseUrl and openSearchUrl to test a remote OpenSearch endpoint: + +``` +$ yarn cypress run --spec "cypress/integration/core-opensearch-dashboards/opensearch-dashboards/*.js" --config "baseUrl=https:///_dashboards" --env "openSearchUrl=https://,SECURITY_ENABLED=true,username=admin,password=xxxxxxxx,ENDPOINT_WITH_PROXY=true" +``` + +`SECURITY_ENABLED`: if true, the `username` and `password` passing in are used as basic authentication credentials during `cy.visit` and `cy.request`. Also, please notice security enabled endpoint normally uses https protocol, so you may want to pass in different urls. + +`ENDPOINT_WITH_PROXY`: for an OpenSearch endpoint wrapped with a proxy that redirects the visiting url to the login url, even with auth option provided in `cy.visit`, the redirection to the login url still happens. So a login request before tests and cache the security cookie are needed and can be switched on by this argument. + +`MANAGED_SERVICE_ENDPOINT`: set to true if tests are running against managed service domains. + +### Formatting + +`prettier` and `ESLint` is integrated and used to standardize formatting of files, where `prettier` takes care of the code formatting and `ESLint` takes care of the code style. You can check the formatting of all files (new and existing) by running + +``` +$ yarn lint +``` +and auto fix the formatting of all files (new and existing) by running +``` +$ yarn lint --fix +``` + +`Husky` precommit hook is used to automatically run `yarn lint`, please fix the files according to lint result before commiting code changes (run `yarn lint --fix` for fixable errors, or manully fix code according to error messages). If you have any doubts on `ESLint` rules, feel free to [open an issue](issues). + + +### Test Development + +#### Experimental Features + +When writing tests for experimental features, please follow these steps. + +1. Figure out the folder location to put the tests + +Similar to the regular tests, OSD Core tests go to the [folder](integration/core-opensearch-dashboards/opensearch-dashboards/) and OSD plugin tests go to the [folder](cypress/integration/plugins/). + +2. Develop tests with a flag to turn on and off + +Add an environment variable (e.g boolean) to only run tests for the experiemental feature when it is true. (Define such in [cypress configuration](cypress.json). Refer to `SECURITY_ENABLED` as an example) This is to ensure backward compatibility when integrating with [opensearch-build repo](https://github.com/opensearch-project/opensearch-build/blob/main/src/test_workflow/integ_test/service_opensearch_dashboards.py) whose OpenSearch Dashboards execution command or yml configuration may not be updated to support the experimental feature yet. + +3. Set up Github action to run the tests inside the current repo + +Create a new workflow by referring to [this template](https://github.com/opensearch-project/opensearch-dashboards-functional-test/blob/main/.github/workflows/release-e2e-workflow-template.yml) for OSD plugin or [this workflow](https://github.com/opensearch-project/opensearch-dashboards-functional-test/blob/main/.github/workflows/cypress-workflow-vanilla-snapshot-based.yml) for OSD Core. This workflow is to run the OSD from artifact. You could enable your experimental feature through either `./bin/opensearch-dashboards --vis_builder.enabled` or through modifying the content of the yml file. (In order to run the tests from the source code repo of the feature, you can set up workflows to check out the source code and use `yarn` to start OSD.) + +4. Run tests from `opensearch-build` + +To make the build repo enable your experimental feature when spinning up OSD service, make sure that you update [this file](https://github.com/opensearch-project/opensearch-build/blob/main/src/test_workflow/integ_test/service_opensearch_dashboards.py) You could either modify the start command or the yml file. To avoid a potentially long start command, it is preferred to modify the yml file to turn on the feature. diff --git a/ONBOARDING.md b/ONBOARDING.md new file mode 100644 index 000000000..32090e482 --- /dev/null +++ b/ONBOARDING.md @@ -0,0 +1,58 @@ +## Onboarding + +To onboard your release tests (Dashboards plugins) onto this repo test function, you can follow the next steps. + +0. Create a name to identify your plugin, e.g `plugin-name` + +The dir name shall be descriptive to identify your plugin. You can use the same name defined in build repo https://github.com/opensearch-project/opensearch-build/tree/main/scripts/components + +1. Place test files under `cypress/integration/plugins/` + +2. Place fixtures under `cypress/fixtures/plugins/` + +3. Place custom commands under `cypress/utils/plugins/`, if it's a general command that could be reused by other plugins, place it under `cypress/utils/commands.js` + +4. Place custom constants under `cypress/utils/plugins/`, reuse the constants in `cypress/utils/base_constants.js` + +5. Run tests + +Start OpenSearch and OpenSearch Dashboards. Then refer to the [test execution file](/integtest.sh). + +E.g if you want to run all plugin tests with security enabled. + +``` +npx cypress run --env SECURITY_ENABLED=true --spec "cypress/integration/plugins/*/*" +``` + +E.g if you want to run AD plugin tests with security enabled. + +``` +npx cypress run --env SECURITY_ENABLED=true --spec "cypress/integration/plugins/anomaly-detection-dashboards-plugin" +``` + +For the complete ways to run Cypress, you can refer to the Cypress official site https://docs.cypress.io/guides/getting-started/.installing-cypress#Opening-Cypress. + +The env parameters are defined in https://github.com/opensearch-project/opensearch-dashboards-functional-test/blob/main/cypress.json where you can look for or add the desired parameters. You can refer to the Cypress official site https://docs.cypress.io/guides/guides/environment-variables#Setting. + +6. [optional] Remove copied tests from your plugin and execute them remotely from your plugin + +Since your release tests have been moved in this repo, to avoid maintain duplicated code and potentially diverged Cypress versions in two repos, you can remove them from your plugin. Then execute the tests inside this repo from your CI. See AD's example https://github.com/opensearch-project/anomaly-detection-dashboards-plugin/blob/main/.github/workflows/remote-integ-tests-workflow.yml However, this can be decided at plugin level to phase out the changes. + +7. [optional] Verify test execution from OpenSearch build repo + +The tests inside this repo will be executed from OpenSearch build repo. You can verify that by running test script from https://github.com/opensearch-project/opensearch-build/tree/main/src/test_workflow Please refer to the repo to the way of test exeuction. Below is the set of commands you can use based on current situation. + +Suppose your plugin is ready for version 1.2.0 + +``` +./build.sh manifests/1.2.0/opensearch-1.2.0.yml + +./build.sh manifests/1.2.0/opensearch-dashboards-1.2.0.yml + +./assemble.sh builds/opensearch/manifest.yml + +./assemble.sh builds/opensearch-dashboards/manifest.yml + +./test.sh integ-test manifests/1.2.0/opensearch-dashboards-1.2.0-test.yml + +``` \ No newline at end of file