Skip to content

Commit 481d4d1

Browse files
pmeulenpmeulen
committed
Update readme
1 parent e708080 commit 481d4d1

File tree

1 file changed

+76
-48
lines changed

1 file changed

+76
-48
lines changed

‎stepup/README.md‎

Lines changed: 76 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -61,99 +61,127 @@ username: admin
6161
password: admin
6262
```
6363

64-
Mailcatcher is included. You can view the email by going to http://localhost:1080
65-
66-
A SimpleSAMLPHP SP is included to test authentication from an SP. It can be accessed at https://ssp.dev.openconext.local/simplesaml/sp.php
64+
There are many user accounts available for testing registration in the selfservice application.
65+
See https://ssp.dev.openconext.local/#test-accounts for a list of test accounts.
66+
We recommend that you use the admin account only to activate additional RA and RAA accounts and do not
67+
use the admin account itself for testing.
6768

6869
The selfservice application is available at https://selfservice.dev.openconext.local
70+
Mailcatcher is included. You can view the emails by going to http://localhost:1080
6971

70-
There are many user accounts available for testing. See http://ssp.dev.openconext.local/#test-accounts
71-
We recommend that you use the admin account only to activate additional RA and RAA accounts and do not
72-
use the admin account itself for testing.
72+
A SimpleSAMLPHP SP is included to test authentication from an SP.
73+
It can be accessed at https://ssp.dev.openconext.local/simplesaml/sp.php
7374

7475
# Version info
7576
You can use the included `version-info.sh` script to get the version info of the different stepup
7677
components from the docker containers. This script will show the `version`, `revision` and `created`
7778
tags of the running containers.
7879

7980
# Starting a project in development mode
80-
81-
You can mount your local directory inside a development container which contains the correct node and composer versions for your project. To do so use the script start-dev-env.sh. You can use this script to mount multiple directories in multiple containers, basically allowing you to start multiple containers in dev mode.
81+
You can mount your local directory inside a development container which contains the correct node and composer versions
82+
for your project. To do so use the script `start-dev-env.sh`. You can use this script to mount multiple directories in
83+
multiple containers, basically allowing you to start multiple containers in dev mode.
8284

8385
To mount the code in just one container:
8486
`start-dev-env.sh webauthn:/home/dan/Stepup-webauthn`
85-
The recommended way is to use absolute paths and the script requires the name of the service and local code path to be separated by a `:`.
87+
The recommended way is to use absolute paths and the script requires the name of the service and local code path to be
88+
separated by a `:`.
8689

8790
To mount the code in multiple containers:
8891
`start-dev-env.sh webauthn:/home/dan/Stepup-webauthn gateway:/home/dan/Stepup-gateway`
8992
You can add as many services+local code paths that you need.
9093
The recommended way is to use absolute paths and the script requires the name of the service and local code path to be separated by a `:`, for each service.
9194

9295
# Accessing the database from your IDE
93-
The Maria DB container exposes her 3306 port to the outside. So you should be able to connect to the database with
94-
your favorite DBA tool. In PHPStorm I was able to connect to the `mariadb` host by using these setting.
95-
96+
The Maria DB container exposes its 3306 port.
97+
So you can connect to the database with your favorite DBA tool on your host.
98+
The connection information is:
9699
```
97100
host: localhost
101+
port: 3306
98102
user: root
99-
password: you know the secret ;)
103+
password: secret
100104
```
101105

102106
# PHP 8.2 for development
103-
The default development container is based on the base image with PHP7.2. You can override this on a per service basis. Uncomment the appropiate line for this in the file ".env" so it uses the PHP8.2 container. An .env.dist is included that you can use to have your own .env. file. .env is in .gitigore so you can make your own changes.
107+
The default development container is based on the base image with PHP7.2.
108+
You can override this on a per service basis.
109+
Uncomment the appropriate line for this in the file ".env" so it uses the PHP8.2 container.
110+
An .env.dist is included that you can use to have your own .env file.
111+
.env is in .gitignore so you can make your own changes.
104112

105113
# Functional testing
106-
The stepup application suite comes with a set of Behat (Gherkin) features. These features test the stepup applications
107-
functionally. These tests range from simple smoketests (can we still vet a token), to more bug report driven
108-
functional tests. And everything in between.
114+
The stepup application suite comes with a set of Behat (Gherkin) features.
115+
These features test the stepup applications functionally.
116+
These tests range from simple smoketests (can we still vet a token), to more bug report driven functional tests.
117+
And everything in between.
109118

110119
These tests live in this folder: `stepup/tests/behat/features`
111120

112-
Custom Contexts where created to perform Stepup specific actions. Some details about these contexts can be read about below.
113-
114-
## Running the tests
115-
1. The tests are automatically triggered on GitHub Actions when building a Pull Request. The action is named: [`stepup-behat`](https://github.com/OpenConext/OpenConext-devconf/actions/workflows/stepup-behat.yml)
116-
2. Run them manually.
121+
Custom Contexts where created to perform Stepup specific actions.
122+
Some details about these contexts can be read about below.
117123

118-
Step two can be achieved by following these actions.
124+
## Running the using github actions
125+
The tests are automatically triggered on GitHub Actions when building a Pull Request.
126+
The action is named: [`stepup-behat`](https://github.com/OpenConext/OpenConext-devconf/actions/workflows/stepup-behat.yml)
119127

120-
1: You must instruct the `devconf` environment that you want to run functional tests.
121-
1. Option 1: Copy the `.env.test` to be the `.env`
122-
2. Option 2: Add these two lines to your existing `.env` file
128+
## Running the test locally
123129

130+
### Starting the containers in test mode
131+
To run the test you need to have a local devconf environment running and prepare it for running the behat tests.
132+
The easiest way to do this is to copy the `.env.test` file to `.env`.
133+
The .env is sourced by the `start-dev-env.sh` script and sets these two environment variables:
124134
```shell
125135
APP_ENV=smoketest
126136
STEPUP_VERSION=test
127137
```
128138

129-
2: Next you should start the devconf containers in test mode
130-
1. `$ ./start-dev-env.sh` will start the environment using test images for every component.
131-
2. `$ ./start-dev-env.sh selfservice:/path/to/SelfService` to start certain components with local code mounted (useful during development)
132-
3. Choose if you want to run the containers in the back- or foreground.
139+
The above will start the environment with the test images for every component, it will also use _test databases.
140+
E.g. `middleware` will become `middleware_test`, `gateway` will become `gateway_test`, etc.
141+
This way your local dev environment is not affected by running the tests if you use the same devconf environment
142+
for both smoke testing and other testing / development.
133143

134-
3: Once the containers are up and running, you can run the behat tests
135-
1. Install the required dependencies in the container `$ docker compose exec behat composer install`
136-
2. Open a shell in the `behat` container `$ docker compose exec behat bash`
137-
3. Run the tests:
138-
1. `./behat` will run all available behat tests that are not excluded using the `@SKIP` tag
139-
2. `./behat features/ra.feature` will only run the `ra.feature` found in the features folder
140-
3. `./behat features/ra.feature:20` will only run the scenario found on line 20 of the `ra.feature`
141-
4. TODO: `./behat --filter=selfservice` will only run features marked with the `@selfservice` tag
144+
Note that you can only run one devconv environment at a time because of the port mappings.
145+
All environments use the same ports and the same docker network names.
146+
147+
You can use the override to run the tests against a local version of the code. E.g.
148+
*`$ ./start-dev-env.sh` will start the environment using test images for every component.
149+
*`$ ./start-dev-env.sh selfservice:/path/to/SelfService` will start selfservice with local code mounted
150+
151+
### Prepare the behat container
152+
153+
The first time you run the behat tests, you need to install the dependencies in the container
154+
```shell
155+
docker compose exec behat composer install
156+
```
157+
158+
### Running the tests
159+
160+
Execute behat in the behat container:
161+
- `docker compose exec behat ./behat` will run all available behat tests that are not excluded using the `@SKIP` tag
162+
- `docker compose exec behat ./behat features/ra.feature` will only run the `ra.feature` found in the features folder
163+
- `docker compose exec behat ./behat features/ra.feature:20` will only run the scenario found on line 20 of the `ra.feature`
142164

143165
## Writing tests
144166
Many of the step definitions are coded in our own Contexts. These contexts are divided into five main contexts.
145-
It should be straightforward where to add new definitions. The contexts are not following all the clean code or solid principles. This code is messy, be warned.
167+
It should be straightforward where to add new definitions.
168+
The contexts are not following all the clean code or solid principles. This code is messy, be warned.
146169

147-
It can be useful during debugging to use the `$this->diePrintingContent();` statement. This outputs the URI of the browser, and the last received html response. As it is hard to step debug the code that is run in a CURL based browser.
170+
It can be useful during debugging to use the `$this->diePrintingContent();` statement.
171+
This outputs the URI of the browser, and the last received html response.
172+
As it is hard to step debug the code that is run in a CURL based browser.
148173

149174
TODO: Mark your tests with at least one of the pre-defined tags:
175+
- `selfservice`
176+
- `ra`
177+
- `gateway`
178+
- `middleware`
179+
- `tiqr`
180+
- `demogssp`
181+
- `webauthn`
182+
183+
These tags match the `devconf` names given to the different components.
150184

151-
`selfservice`
152-
`ra`
153-
`gateway`
154-
`middleware`
155-
`tiqr`
156-
`demogssp`
157-
`webauthn`
185+
After that we can use the tags to run only the tests that are relevant for a specific component.
186+
E.g.: `docker compose exec behat ./behat --filter=selfservice` will only run features marked with the `@selfservice` tag
158187

159-
Note that these tags match the `devconf` names given to the different components.

0 commit comments

Comments
 (0)