You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Update/refactor some cypress documentation
* Fixes some whitespace/grammar/typos
* Condenses the explanation/instructions for the different modes of
execution
* Condense Artifacts section
This is a big sprawling file; trying to cut down on the noise.
* Move test-running section to top of README
This is going to be what 90% of readers are looking for, methinks.
* Adds Security Solution's cypress suite to x-pack testing README
* Fix broken link
This file was moved as part of #64368.
* Remove broken link
This file was deleted in #67138.
* Apply suggestions from code review
Co-authored-by: Devin W. Hurley <snowmiser111@gmail.com>
* Fix typo
Co-authored-by: Devin W. Hurley <snowmiser111@gmail.com>
Copy file name to clipboardExpand all lines: x-pack/README.md
+4-3Lines changed: 4 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -84,8 +84,9 @@ Jest integration tests can be used to test behavior with Elasticsearch and the K
84
84
yarn test:jest_integration
85
85
```
86
86
87
-
An example test exists at [test_utils/jest/integration_tests/example_integration.test.ts](test_utils/jest/integration_tests/example_integration.test.ts)
88
-
89
87
#### Running Reporting functional tests
90
88
91
-
See [here](test/reporting/README.md) for more information on running reporting tests.
89
+
See [here](./test/functional/apps/dashboard/reporting/README.md) for more information on running reporting tests.
The `security_solution/cypress` directory contains functional UI tests that execute using [Cypress](https://www.cypress.io/).
4
4
5
-
## Folder Structure
5
+
## Running the tests
6
6
7
-
### Fixtures (Cypress native folder)
7
+
There are currently four ways to run the tests, comprised of two execution modes and two target environments, which will be detailed below.
8
8
9
-
Fixtures are used as external pieces of static data when we stub responses.
9
+
### Execution modes
10
10
11
-
###Integration (Cypress native folder)
11
+
#### Interactive mode
12
12
13
-
Contains the specs that are going to be executed.
13
+
When you run Cypress in interactive mode, an interactive runner is displayed that allows you to see commands as they execute while also viewing the application under test. For more information, please see [cypress documentation](https://docs.cypress.io/guides/core-concepts/test-runner.html#Overview).
14
14
15
-
###Objects
15
+
#### Headless mode
16
16
17
-
Objects are a representation of data used accross different tests.
17
+
A headless browser is a browser simulation program that does not have a user interface. These programs operate like any other browser, but do not display any UI. This is why meanwhile you are executing the tests on this mode you are not going to see the application under test. Just the output of the test is displayed on the terminal once the execution is finished.
18
18
19
-
### Pluggins (Cypress native folder)
19
+
### Target environments
20
20
21
-
By default Cypress will automatically include the plugins file cypress/plugins/index.js before every single spec file it runs. They do this purely as a convenience mechanism so you don’t have to import this that in every single one of your spec files.
21
+
#### FTR (CI)
22
22
23
-
### Screens
23
+
This is the configuration used by CI. It uses the FTR to spawn both a Kibana instance (http://localhost:5620) and an Elasticsearch instance (http://localhost:9220) with a preloaded minimum set of data (see preceding "Test data" section), and then executes cypress against this stack. You can find this configuration in `x-pack/test/security_solution_cypress`
24
24
25
-
In _screens_ folder we are going to find all the elements we want to interact in our tests.
25
+
#### Custom Targets
26
26
27
-
Each file inside the tasks folder represents a screen of our application. When the screens are complex i.e. Hosts contains multiple tabs, the page is represented by a folder and the different important parts are represented by files.
27
+
This configuration runs cypress tests against an arbitrary host.
28
+
**WARNING**: When using your own instances you need to take into account that if you already have data on it, the tests may fail, as well as, they can put your instances in an undesired state, since our tests uses es_archive to populate data.
28
29
29
-
i.e.
30
-
- tasks
31
-
- hosts
32
-
- all_hosts.ts
33
-
- authentications.ts
34
-
- events.ts
35
-
- main.ts
36
-
- uncommon_processes.ts
37
-
38
-
### Tasks
30
+
### Test Execution: Examples
39
31
40
-
_Tasks_ are functions that my be re-used across tests.
32
+
#### FTR + Headless
41
33
42
-
Each file inside the tasks folder represents a screen of our application. When the screens are complex i.e. Hosts contains multiple tabs, the page is represented by a folder and the different important parts are represented by files.
34
+
Since this is how tests are run on CI, this will likely be the configuration you want to reproduce failures locally, etc.
43
35
44
-
i.e.
45
-
- tasks
46
-
- hosts
47
-
- all_hosts.ts
48
-
- authentications.ts
49
-
- events.ts
50
-
- main.ts
51
-
- uncommon_processes.ts
52
-
53
-
### URLs
54
-
55
-
Represents all the URLs used during the tests execution.
56
-
57
-
## Test data
36
+
```shell
37
+
# bootstrap kibana from the project root
38
+
yarn kbn bootstrap
58
39
59
-
The data the tests need:
60
-
- Is generated on the fly using our application APIs (preferred way)
61
-
- Is ingested on the ELS instance using es_archive
40
+
# build the plugins/assets that cypress will execute against
41
+
node scripts/build_kibana_platform_plugins
62
42
63
-
By default when running the tests on Jenkins mode a base set of data is ingested on the ELS instance: an empty kibana index and a set of auditbeat data (the `empty_kibana` and `auditbeat` archives, respectively). This is usually enough to cover most of the scenarios that we are testing.
43
+
# launch the cypress test runner
44
+
cd x-pack/plugins/security_solution
45
+
yarn cypress:run-as-ci
46
+
```
64
47
65
-
###How to generate a new archive
48
+
#### FTR + Interactive
66
49
67
-
We are using es_archiver in order to manage the data that our Cypress tests needs.
50
+
This is the preferred mode for developing new tests.
68
51
69
-
1. Setup if possible a clean instance of kibana and elasticsearch (if not, possible please try to clean the data that you are going to generate).
70
-
2. With the kibana and elasticsearch instance up and running, create the data that you need for your test.
71
-
3. When you are sure that you have all the data you need run the following command from: `x-pack/plugins/security_solution`
52
+
```shell
53
+
# bootstrap kibana from the project root
54
+
yarn kbn bootstrap
72
55
73
-
```sh
74
-
node ../../../scripts/es_archiver save <nameOfTheFolderWhereDataIsSaved><indexPatternsToBeSaved> --dir ../../test/security_solution_cypress/es_archives --config ../../../test/functional/config.js --es-url http://<elasticsearchUsername>:<elasticsearchPassword>@<elasticsearchHost>:<elasticsearchPort>
75
-
```
56
+
# build the plugins/assets that cypress will execute against
When you run the Cypress on interactive mode, an interactive runner is displayed that allows you to see commands as they execute while also viewing the application under test.
82
+
## Folder Structure
93
83
94
-
For more information, please visit: https://docs.cypress.io/guides/core-concepts/test-runner.html#Overview
84
+
### integration/
95
85
96
-
#### Headless mode
86
+
Cypress convention. Contains the specs that are going to be executed.
97
87
98
-
A headless browser is a browser simulation program that does not have a user interface. These programs operate like any other browser, but do not display any UI. This is why meanwhile you are executing the tests on this mode you are not going to see the application under test. Just the output of the test is displayed on the terminal once the execution is finished.
88
+
### fixtures/
99
89
100
-
### Emulating Jenkins vs your own instances
90
+
Cypress convention. Fixtures are used as external pieces of static data when we stub responses.
101
91
102
-
#### Emulating Jenkins
92
+
###plugins/
103
93
104
-
With this mode we use the FTR to run the Cypress tests and automatically, a Kibana instance (http://localhost:5620) and Elastic Search instance (http://localhost:9220) with a preloaded minimum set of data.
94
+
Cypress convention. As a convenience, by default Cypress will automatically include the plugins file cypress/plugins/index.js before every single spec file it runs.
105
95
106
-
You can find the configuration of this mode in `x-pack/test/security_solution_cypress`
96
+
### objects/
107
97
108
-
#### Your own instances
98
+
Contains representations of data used across different tests; our domain objects.
109
99
110
-
When using your own instances you need to take into account that if you already have data on it, the tests may fail, as well as, they can put your instances in an undesired state, since our tests uses es_archive to populate data.
100
+
### screens/
111
101
102
+
Contains the elements we want to interact with in our tests.
112
103
113
-
### Running Cypress in Headless mode as a Jenkins execution (The preferred way when running regressions on your machine)
104
+
Each file inside the screens folder represents a screen in our application. When the screens are complex, e.g. Hosts with its multiple tabs, the page is represented by a folder and the different important parts are represented by files.
114
105
115
-
1. First bootstrap kibana changes from the Kibana root directory:
106
+
Example:
116
107
117
-
```sh
118
-
yarn kbn bootstrap
119
-
```
108
+
- screens
109
+
- hosts
110
+
- all_hosts.ts
111
+
- authentications.ts
112
+
- events.ts
113
+
- main.ts
114
+
- uncommon_processes.ts
120
115
121
-
2. Build the plugins
116
+
### tasks/
122
117
123
-
```sh
124
-
node scripts/build_kibana_platform_plugins
125
-
```
118
+
_Tasks_ are functions that may be reused across tests.
126
119
127
-
3. Launch Cypress command line test runner:
120
+
Each file inside the tasks folder represents a screen of our application. When the screens are complex, e.g. Hosts with its multiple tabs, the page is represented by a folder and the different important parts are represented by files.
128
121
129
-
```sh
130
-
cd x-pack/plugins/security_solution
131
-
yarn cypress:run-as-ci
132
-
```
122
+
Example:
133
123
134
-
As explained previously, this type of execution you don't need to have running a kibana and elasticsearch instance. This is because the command, as it would happen in the CI, will launch the instances. The elasticsearch instance will be fed data found in: `x-pack/test/security_solution_cypress/es_archives`
135
-
136
-
### Running Cypress in Interactive mode as a Jenkins execution (The preferred way when developing new cypress tests)
124
+
- tasks
125
+
- hosts
126
+
- all_hosts.ts
127
+
- authentications.ts
128
+
- events.ts
129
+
- main.ts
130
+
- uncommon_processes.ts
137
131
138
-
1. First bootstrap kibana changes from the Kibana root directory:
132
+
### urls/
139
133
140
-
```sh
141
-
yarn kbn bootstrap
142
-
```
134
+
Represents all the URLs used during the tests execution.
143
135
144
-
2. Build the plugins
136
+
## Test data
145
137
146
-
```sh
147
-
node scripts/build_kibana_platform_plugins
148
-
```
138
+
The data the tests need:
149
139
150
-
3. Launch Cypress command line test runner:
140
+
- Is generated on the fly using our application APIs (preferred way)
141
+
- Is ingested on the ELS instance using the `es_archive` utility
151
142
152
-
```sh
153
-
cd x-pack/plugins/security_solution
154
-
yarn cypress:open-as-ci
155
-
```
143
+
By default, when running the tests in Jenkins mode, a base set of data is ingested on the ELS instance: an empty kibana index and a set of auditbeat data (the `empty_kibana` and `auditbeat` archives, respectively). This is usually enough to cover most of the scenarios that we are testing.
156
144
157
-
As explained previously, this type of execution you don't need to have running a kibana and elasticsearch instance. This is because the command, as it would happen in the CI, will launch the instances. The elasticsearch instance will be fed data found in: `x-pack/test/security_solution_cypress/es_archives`
158
-
159
-
### Running Cypress in your own instances (Recommended just for releases regressions)
145
+
### How to generate a new archive
160
146
161
-
1. First bootstrap kibana changes from the Kibana root directory:
147
+
**Note:** As mentioned above, archives are only meant to contain external data, e.g. beats data. Due to the tendency for archived domain objects (rules, signals) to quickly become out of date, it is strongly suggested that you generate this data within the test, through interaction with either the UI or the API.
162
148
163
-
```sh
164
-
yarn kbn bootstrap
165
-
```
149
+
We use es_archiver to manage the data that our Cypress tests need.
166
150
167
-
2. Load the initial auditbeat set of data needed for the test execution:
151
+
1. Set up a clean instance of kibana and elasticsearch (if this is not possible, try to clean/minimize the data that you are going to archive).
152
+
2. With the kibana and elasticsearch instance up and running, create the data that you need for your test.
153
+
3. When you are sure that you have all the data you need run the following command from: `x-pack/plugins/security_solution`
Note that the command will create the folder if it does not exist.
166
+
167
+
## Development Best Practices
181
168
182
169
### Clean up the state
183
170
184
-
Remember to use the `cleanKibana`method before starting the execution of the test
171
+
Remember to clean up the state of the test after its execution, typically with the `cleanKibana`function. Be mindful of failure scenarios, as well: if your test fails, will it leave the environment in a recoverable state?
185
172
186
173
### Minimize the use of es_archive
187
174
188
-
When possible, create all the data that you need for executing the tests using the application APIS.
175
+
When possible, create all the data that you need for executing the tests using the application APIS or the UI.
189
176
190
177
### Speed up test execution time
191
178
@@ -194,54 +181,25 @@ taken into consideration until another solution is implemented:
194
181
195
182
- Group the tests that are similar in different contexts.
196
183
- For every context login only once, clean the state between tests if needed without re-loading the page.
197
-
- All tests in a spec file must be order-independent.
198
-
199
-
Remember that minimizing the number of times the web page is loaded, we minimize as well the execution time.
200
-
201
-
## Reporting
202
-
203
-
When Cypress tests are run on the command line via non visual mode
204
-
reporting artifacts are generated under the `target` directory in the root
205
-
of the Kibana, as detailed for each artifact type in the sections below.
206
-
207
-
### HTML Reports
208
-
209
-
An HTML report (e.g. for email notifications) is output to:
0 commit comments