Behat

Running Behat with debugging

You can connect to the selenium container via VNC to view what is being executed in the browser, which is very helpful for when writing/fixing tests.

There are a few different selenium debug containers that you may want to use depending what Totara version and Browser you wish to test against:

Container Name	Browser	Totara Version	Port	Apple Silicon Support
selenium-chrome-debug	Chromium 126.0	Totara 19+	5902	✅ Runs natively
selenium-chrome-debug-legacy	Chrome 102.0	Totara 18 and older	5903	⚠️ Requires overriding image
selenium-chrome-debug-latest	Chromium latest	Totara 19+	5904	✅ Runs natively
selenium-firefox-debug	Firefox latest	Totara 19+	5905	✅ Runs natively
selenium-edge-debug	Edge latest	Totara 19+	5906	❌ Unsupported

Generally if testing Totara 19 or newer, you'll want to use the selenium-chrome-debug (Chrome 126) container.

For Totara 18 and older, use selenium-chrome-debug-legacy (Chrome 102)

Now start the selenium debug container you wish to use:

tup selenium-chrome-debug

Note: Behat uses the production tui build files, and not the development ones. You will need to build them and purge caches if you haven't already built them since making front end changes.

Initiate the behat tests:

cd sitefolder # must run the command from the root of your Totara repo
tnpm run tui-build-prod
tzsh php-8.3 # or any other php container
purge # purges any cached front end code
installbehat

Run behat with:

# Run a specific scenario
behat --name="Name of the scenario"

# Run a specific feature file (the path must be relative to the site root or the full path)
behat path/to/feature/file

# Run a specific tag
behat --tags=@totara

Note that to use interactive steps like And I pause you must use the behat alias rather than executing test/behat/behat.php.

Set up and open a VNC client and connect to it.

MacOS VNC Client Instructions

---

1. Open the Screen Sharing app (can find it via Spotlight/Cmd+Space)
2. Enter in vnc://localhost:PORT - where PORT is the port for the selenium container you wish from the table above
3. Click Connect
4. Enter in secret as the password and remember it

---

Windows VNC Client Instructions

---

You'll need a VNC client installed if you are on Windows.

RealVNC and TightVNC are good options.

Connect using the following credentials:

• Host: localhost
• Port: For the selenium container you wish from the table above
• Password: secret

---

If you want to view a summary of the errors for the previous run, you can simply run behatlogs within the container.

If you can't see the scenario executing, it may be because the scenario is missing the @javascript tag. If the tag isn't specified for the scenario it will run it in headless mode, meaning selenium won't be used.

Running Behat in parallel

If you just want to run a suite of behat tests, then it is much faster (and recommended) to run behat in parallel mode (i.e. across multiple threads simultaneously)

If you are using the example config.php that comes with docker-dev, simply find $DOCKER_DEV->behat_parallel and set it to true. If you are not using the example config.php, then you'll need to set your behat host to selenium-hub in your config.php.

You'll then need to start the selenium containers. For the following examples, we are going to run behat across 4 threads. You can adjust this number based on your computer's performance.

Mac M1/M2/M3/M4 Important Note: You'll want to override the default selenium containers for better performance on Apple Silicon. See here for more information.

tup selenium-hub
tscale selenium-chrome 4 # Creates 4 selenium containers for running across 4 threads

Totara 13+ Note: Behat uses the production tui build files, and not the development ones. You will need to build them and purge caches if you haven't already built them since making front end changes.

Log into one of the PHP containers:

cd sitefolder # must run the command from the root of your Totara repo
tnpm run tui-build-prod # t13+ only - tui build for behat
tzsh php-7.4 # or any other php container
purge # purges any cached front end code

Initiate the behat tests:

# See shell/totara-aliases.sh for what these aliases do

# Initiate behat for the number of threads defined in $DOCKER_DEV->behat_parallel_count in config.php
installbehat

# If you are wanting to run a specific tag, then you can optimise behat for it
installbehat --optimise-runs=@totara

Run behat with:

# Run all scenarios (takes several hours)
behat

# Run a specific tag (make sure that you optimiszed the tag via `installbehat --optimise-runs=@totara`)
behat --tags=@totara

If you want to view a summary of the errors for the previous run, you can simply run behatlogs within the container.

To see the status of the selenium containers while they are executing, go to http://localhost:4444/grid/console to view the web console.