Use Drupal Flake for PHPUnit testing

Drupal Flake is a new way of doing local Drupal development (running a self-contained Drupal site on your desktop or laptop). It's a project I started earlier this year, as an experimental development environment on NixOS. I've been using Docker in one form or another for Drupal development for the past 15 years -- DDev for the past 6 or so.

DDev is a great way to do Drupal development, and has become the standard way for most of the Drupal Community. But here's a little secret -- Drupal Flake is even better!

DDev is a program that manages Docker containers so that regardless of what platform you're on, you have the same environment, the same tools, so you know it works the same way.

Drupal Flake does essentially the same thing -- but instead of using Docker containers to get repeatability, it uses a Nix "flake".

Nix is at its heart a functional language, and a package manager. It's entirely cross-platform, and packages up platform-specific binaries. A "flake" is a file that defines packages, dev shell environments, applications, user settings, or entire operating systems among other things, and it's a great way to manage a development environment. Nix flakes can be very simple, just making packages and tools available for easy development -- but running a Drupal site is not quite so simple, because it depends upon a running database, language server, and web server. This is why Docker has been such a widespread solution... DDev uses Docker Compose to run multiple containers to get a running site. But Nix can do the same thing -- without containers! And the huge advantage of this is you can use all your shell tools right in the context of your development environment, and you don't have to drop into a limited shell inside a container.

If you're a shell junkie like me, you may know about the amazing power of tools like ripgrep, fzf, yazi, and Neovim. Sure you can install these inside DDev containers -- but it's a hassle to have to do so, and it slows things down. When you're using Drupal Flake, all your tools are just there, ready for use. And furthermore, drush, composer, phpcs/phpcbf, all just work.

Drupal Flake is more than just a simple development flake for Drupal -- it's becoming a full-fledged special purpose development environment for Drupal, with its own set of tools. It's come quite a ways since I introduced it at DrupalCon back in March 2025. It's now built to be a fast way to get a local site up and running, with good debugging support, a simple update mechanism, the ability to install other packages, and now, support for running phpunit tests!

Set up a local dev copy of an existing Drupal site

This is now a breeze with Drupal Flake. This does assume you have Nix installed, with "nix-command" and "flake" experimental options set already (the easiest way to do this is use the Determinate Systems installer). It's also useful to have Direnv active.

1. Clone a copy of your Drupal site, and change directory into it.
2. Run `nix flake init -t github:freelock/drupal-flake` to "install" the flake in the directory.
3. Copy the .env.example file to .env, and edit it to provide your project name, php version, port to use, and the path to the docroot (if it's not web).
4. If your site is already in git, `git add flake.* .env .services` (at a minimum) -- Nix flakes ignore uncommitted files.
5. If you are using direnv, run `direnv allow` to start building the environment. If not, use `nix develop`.
6. You should now have the flake environment set up. Entering `?` prints a bunch of available commands. `start-detached` will fire up all the servers -- mariadb, nginx, php-fpm.
7. Wait for the servers to start -- you can use `pc-status` to see their status -- it can take 15 - 20 seconds to all come up.
8. Import a copy of your database -- I typically use `drush sqlc < /path/to/downloaded/db.sql`. 

You can now use `drush uli` to log in.

Set up PHPUnit

This is still very much experimental, but try it out and let me know here or in the Drupal.org issue queue if you have any trouble. So far I've only used PHP8.3 with a Drupal 11.2 site.

For first-time setup:

phpunit-setup -c

This uses composer require --dev to install PHPUnit and other necessary dev packages to the project's dev dependencies. It also provides instructions for applying the core patch needed for running PHPUnit with non-standard unix_socket paths (which is necessary for tests to run in this environment). Note that the one-line patch does point directly at a Drupal.org patch location that could be changed -- it's always best practice to download a patch and apply it from your local directory instead of pointing to an external URL that might change.

Next, if necessary:

composer install

... to make sure the patch is applied, or install your dev dependencies if you previously had them set up.

When you're ready to start testing, you need to have a phpunit.xml file in the site root, and Drupal's testing framework expects to have test paths set up at web/sites/simpletest. That's now simple to do:

phpunit-setup

... sets this all up for you! So now you're ready to

Run PHPUnit tests

Now you can simply run phpunit tests using phpunit as you would anywhere. Note that $PROJECT/vendor/bin is already in your path, so `phpunit` can be run without needing to pass in `../vendor/bin`. You can just do `phpunit web/modules/contrib/modulename/` to run all the tests in "modulename". You can test individual test classes by providing the path to that test, and use --filter to specify a single test to run.

The flake does provide a couple other helpers:

phpunit-module <modulename>

... this searches for a module or theme named modulename, and runs all of its tests.

phpunit-custom

... this runs all tests in all modules in web/modules/custom.