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
Copy file name to clipboardExpand all lines: deps/rabbitmq_management/selenium/README.md
+72-72
Original file line number
Diff line number
Diff line change
@@ -1,71 +1,47 @@
1
1
# Automated End-to-End testing of the management ui with Selenium
2
2
3
-
We are using Selenium webdriver to simulate running the management ui in a browser.
4
-
And Mocha as the testing framework for Javascript.
3
+
Selenium webdriver is used to drive web browser's interactions on the management ui.
4
+
And Mocha is used as the testing framework for Javascript.
5
5
6
-
To run the tests we need:
6
+
The following must be installed to run the tests:
7
7
- make
8
8
- docker
9
+
- curl
9
10
10
-
# How tests are organized
11
+
# Organization of test cases
11
12
12
-
All test cases and their configuration files are under the `test` folder and grouped into subfolders based on the area of functionality they are testing. For instance, under `oauth` folder, we have test cases about OAuth 2.0.
13
-
Furthermore, within an area of functionality like OAuth 2.0 we want to test under different configuration.
14
-
For instance under`test/oauth/with-sp-initiated` we group all test cases which run against an Authorization server via the Authorization Code Flow. Whereas under`test/oauth/with-idp-down` we group all test cases which run against an Authorization server which is down.
13
+
`test` folder contains the test cases written in Javascript using Selenium webdriver. Test cases are grouped into folders based on the area of functionality.
14
+
For instance, `test/basic-auth` contains test cases that validates basic authentication. Another example, a bit
15
+
more complex, is`test/oauth` where the test cases are stored in subfolders. For instance,`test/oauth/with-sp-initiated` which validate OAuth 2 authorization where users come to RabbitMQ without any token and RabbitMQ initiates the authorization process.
15
16
16
-
And under `suites` folder we have the test suites. A test suite is a script which executes all test cases
17
-
under a folder and using a given configuration and launching a number of components the test suite depends on.
17
+
The `test` folder also contains the necessary configuration files. For instance, `test/basic-auth` contains `rabbitmq.conf` file which is also shared by other test cases such as `test/definitions` or `test/limits`.
18
18
19
-
Some test cases only depend on RabbitMQ such as the `basic-auth.sh`. In this test suite, we specify the location of the test case relative to the `test` folder.
20
-
And we call the function `run`. We always have to source the file under `bin/suite_template`.
19
+
`suites` folder contains one bash script per test suite. A test suite executes all the test cases under
20
+
a folder with certain configuration. More on configuration on the next section.
21
21
22
-
```
23
-
TEST_CASES_PATH=/basic-auth
24
-
25
-
source $SCRIPT/../bin/suite_template
26
-
run
27
-
````
28
-
29
-
When our test suite requires of other components such as UAA, we use the function call `runWith` as we see below for the test case `oauth-with-uaa.sh`. In this test case, in addition to declaring the location of the test case, we also specify the location of the configuration files required to launch the components this suite
30
-
depends on. We also specify which profiles are activated which in turn defines the settings and configuration files used in the suite. And said earlier, the suite runs via the function `runWith` specifying the components that should be started and stopped and its logs captured too.
31
-
32
-
```
33
-
TEST_CASES_PATH=/oauth/with-sp-initiated
34
-
TEST_CONFIG_PATH=/oauth
35
-
PROFILES="uaa uaa-oauth-provider"
36
-
37
-
source $SCRIPT/../bin/suite_template
38
-
runWith uaa
39
-
40
-
```
22
+
`bin` folder contains as it is expected utility scripts used to run the test suites.
41
23
42
24
43
25
# How to run the tests
44
26
45
27
There are two ways to run the tests.
46
28
47
-
**The interactive mode** - If we are writing code in any of RabbitMQ plugins or
48
-
libraries, we most likely want to run tests interactively, i.e. against our local installed Chrome browser, so that we
49
-
can see the simulated user interactions in the browser. In this mode, we are also running RabbitMQ directly
50
-
from source to speed things up. Otherwise, we would have to build a docker image for every change we wanted to test.
29
+
**Headless mode** - This is the mode used by the CI. But you can also run it locally. In this mode, you do
30
+
not see any browser interaction, everything happens in the background, i.e. rabbitmq, tests, the browser, and any component the test depends on such as UAA.
51
31
52
-
**Headless mode** - If we are not making any code changes to RabbitMQ and instead
53
-
we are only writing tests or simply we want to run them, then we want to run the tests in headless mode.
32
+
**The interactive mode** - This mode is convenient when we are still working on RabbitMQ source code and/or in the selenium tests. In this mode, you run RabbitMQ and tests directly from source to speed things up. The components, such as, UAA or keycloak, run in docker.
54
33
55
-
**IMPORTANT**: RabbitMQ and UAA configuration is different for each mode. The reason is the hostname used
56
-
for both, RabbitMQ and UAA. In headless mode, everything runs in containers and we refer to each container but its
57
-
name, e.g. `rabbitmq` or `uaa`. Whereas in interactive mode, we run most of the components locally (i.e `localhost`), such as RabbitMQ or UAA.
58
34
59
35
## Run tests in headless-mode
60
36
61
-
In this mode, we run suite of tests. This is how to run one suite:
37
+
To run just one suite, you proceed as follows:
62
38
```
63
39
suites/oauth-with-uaa.sh
64
40
```
65
41
66
-
And this is how we run all suites:
42
+
And to is run all suites, like the CI does, you run:
67
43
```
68
-
run-suites.sh
44
+
./run-suites.sh
69
45
```
70
46
71
47
If you want to test your local changes, you can still build an image with these 2 commands from the
@@ -81,61 +57,85 @@ The last command prints something like this:
81
57
=> => naming to docker.io/pivotalrabbitmq/rabbitmq:3.11.0-rc.2.51.g4f3e539.dirty 0.0s
82
58
```
83
59
84
-
To run a suite with a particular docker image we do it like this:
60
+
To run a suite with a particular docker image you do it like this:
## Run tests interactively using your local chrome browser
91
67
92
-
In this mode when we are actively developing and hence we need full control of the
93
-
runtime environment for the tests.
94
-
For this reason, every test suite should have its own Makefile to help developer bootstrap
95
-
the required runtime.
96
-
97
-
Let's say we want to run the test suite `test/oauth/with-uaa`. We proceed as follows:
98
-
99
-
Get node.js dependencies ready. Selenium tests are ultimately written in Javascript and
100
-
requires node.js runtime to run them:
68
+
First you make sure that you have Node.js ready to run the test cases.
101
69
```
102
70
cd selenium
103
71
npm install
104
72
```
105
73
106
-
Start UAA:
74
+
Before you can run a single test case or all the test cases for a suite, you need to
75
+
run RabbitMQ from source and all the components the test cases depends on, if any.
76
+
77
+
For instance, say you want to run the test cases for the suite `suites/oauth-with-uaa.sh`.
78
+
79
+
First, open a terminal and launch RabbitMQ in the foreground:
107
80
```
108
-
cd test/oauth
109
-
make start-uaa
81
+
suites/oauth-with-uaa.sh start-rabbitmq
110
82
```
111
83
112
-
Start RabbitMQ from source (it runs `make run-broker`):
84
+
Then, launch all the components, the suite depends on, in the background:
113
85
```
114
-
make start-rabbitmq
86
+
suites/oauth-with-uaa.sh start-others
115
87
```
116
88
117
-
To run all tests under `with-uaa`:
89
+
And finally, run all the test cases for the suite:
118
90
```
119
-
make test TEST=with-uaa
91
+
suites/oauth-with-uaa.sh test
120
92
```
121
-
Or to run a single tests under the suite:
93
+
94
+
Or just one test case:
122
95
```
123
-
make test TEST=with-uaa/landing.js
96
+
suites/oauth-with-uaa.sh test happy-login.js
124
97
```
125
98
126
-
**VERY IMPORTANT NOTE**: `make start-rabbitmq` will always load `rabbitmq-localhost.config`
127
-
regardless of the test suite we are running. Therefore, if your suite requires a specific
128
-
configuration ensure that configuration is in `rabbitmq-localhost.config`.
99
+
**NOTE**: Nowadays, it is not possible to run all test in interactive mode. It is doable but it has not
100
+
been implemented yet.
101
+
102
+
103
+
## Test case configuration
104
+
105
+
RabbitMQ and other components such as UAA, or Keycloak, require configuration files which varies
106
+
depending on the test case scenario. These configuration files must be dynamically generated using these two other files:
107
+
- one or many configuration files
108
+
- and one or many **.env** file which declare environment variables used to template the former configuration file in order to generate a final configuration file
109
+
110
+
Configuration files may contain reference to environment variables. And configuration files
111
+
may should follow this naming convention: `<prefix>[.<profile>]*<suffix>`. For instance:
112
+
-`basic-auth/rabbitmq.conf` It is a configuration file whose **prefix** is `rabbitmq`, the **suffix** is `.conf` and it has no profile associated to it. Inside, it has no reference to environment variables hence the final
113
+
configuration file is the raw configuration file.
114
+
-`oauth/rabbitmq.conf` Same as `basic-auth/rabbitmq.conf` but this file does have reference to environment variables so the final file will have those variable replaced with their final values
115
+
-`oauth/rabbitmq.mgt-prefix.conf` It is a configuration file with the profile `mgt-prefix`
116
+
117
+
The .env files should follow the naming convention: `.env.<profile>[.<profile>]*`. For instance:
118
+
-`.env.docker` It is an .env file which is used when the profile `docker` is activated
119
+
-`oauth/.env.docker.uaa` It is a .env file used when using `oauth` as test folder and the profiles `docker` and `uaa` are both activated
129
120
130
-
If you had a specific configuration file, such as `rabbitmq-localhost-keycloak.config` you can run
131
-
`make start-rabbitmq` with that configuration like this:
121
+
To generate a `rabbitmq.conf` file the process is as follows:
122
+
1. Merge any applicable .env file from the test case's configuration folder and from the parent folder, i.e. under `/test` folder and generate a `/tmp/rabbitmq/.env` file
123
+
2. Merge any applicable rabbitmq.conf file from the test case's configuration and resolve all the environment variable using `/tmp/rabbitmq/.env` file to produce `/tmp/selenium/<test-suite-name>/rabbitmq/rabbitmq.conf`
124
+
125
+
## Profiles
126
+
127
+
The most common profiles are:
128
+
-`docker` profile used to indicate that RabbitMQ, the tests and selenium+browser run in docker. This profile is automatically activated when running in headless mode
129
+
-`local` profile used to indicate that RabbitMQ and the tests and the browser run locally. This profile is
130
+
automatically activated when running in interactive mode
131
+
132
+
The rest of the components the test cases depends on will typically run in docker such as uaa, keycloak, and the rest.
133
+
134
+
Besides these two profiles, mutually exclusive, you can have as many profiles as needed. It is just a matter of naming the appropriate file (.env, or rabbitmq.conf, etc) with the profile and activating the profile in the test suite script. For instance `suites/oauth-with-uaa.sh` activates two profiles by declaring them in `PROFILES` environment variable as shown below:
132
135
```
133
-
make RABBITMQ_CONFIG_FILE=rabbitmq-localhost-keycloak.config start-rabbitmq
136
+
PROFILES="uaa uaa-oauth-provider"
134
137
```
135
138
136
-
We do not have this issue when we run the headless suites because they use dedicated files
137
-
for each suite. Doing the same when running locally, i.e using `localhost`, would be too tedious.
138
-
139
139
## Chrome vs Chrome driver version mismatch
140
140
141
141
If you find the following error when you first attempt to run one of the selenium tests
0 commit comments