Browser testing can be a powerful way to build confidence in your codebase, and it's easy to get started in a Phoenix app with Wallaby.
I gave a conference talk about this at The Big Elixir 2022 with a few more examples. If you just want to dive into the code, it can be found here.
What is Wallaby?
Wallaby is a browser testing tool written in Elixir that allows you to drive a browser, and write browser-based tests all without leaving the Elixir ecosystem. So you have access to all your favorite tools like ExUnit.
Add the dependency to your mix.exs:
How you install the chromedriver is going to depend on your preferences. On MacOS you can install it with brew but the latest security updates make that a little more painful and less cross-platform friendly in the event that cross-platform matters to you.
Finally, the easiest cross-platform option that I've found is just installing it via npm.
Update the endpoint
You need to update the endpoint.ex to leverage Ecto's SQL sandbox, which allows your concurrent/async tests to be isolated at the database layer.
You also need to modify the socket connect_info to include :user_agent this means that the user agent information is passed along to the socket. The user agent is how Wallaby links up which isolated sandbox database process should be connected with the particular browser test session.
Update the test helper
We need to ensure Wallaby is started as part of running your tests:
Update the test config
You now want to configure your application in test to use the Ecto SQL sandbox, and then you need to configure Wallaby.
A few of the options that you may want to consider modifying include:
screenshot_on_failure - this option ensures that the . You can also configure the path to where the screenshots ought to be dumped.
chromedriver - includes the path to find the chromedriver binary, as well as headless mode, which determines if you'll see the actual browser bootup and take the actions you've given it, or if it will run in the background.
Add the on_mount hook
If you're using Phoenix LiveView you'll also need to add an on_mount hook, which leverages the mount lifecycle hook to ensure that on each LiveView mount the browser and test instance are correctly wired up together.
Note that this assumes Phoenix LiveView version 0.17.7. Things may have changed for you.
Below is an example hook implementation:
You'll then need to update the router to use this on_mount hook for each of your LiveView sessions with the live_session helper.
Setup a FeatureCase
This one is optional, but I've found it useful for developer ergonomics when you're building with Wallaby. It sets up an ExUnit case similar to the generated ConnCase, but geared specifically for Wallaby.