Fixtures
Check against the database state your module actually lives in, not a bare install.
Checks run against a clean minimal install by default. That is the right default — it is reproducible and it is what CI does — but plenty of modules cannot be meaningfully exercised against an empty site. If your module manages vocabulary terms you need terms; if it configures form displays you need content types with fields. A fixture captures that setup once instead of rebuilding it every time.
upkeep check pathauto 12 --fixture=smokeupkeep patch:check pathauto 3597857 --fixture=smokeAn unknown fixture name aborts before any check runs, rather than quietly testing against the wrong state.
What a fixture is
Section titled “What a fixture is”A named gzipped SQL dump, <name>.sql.gz, and a generated manifest beside it,
<name>.yml. The dump is the portable source of truth — it is what you
commit, share and keep — and the manifest is what makes it mean anything
anywhere else. It is managed by the companion
ddev-upkeep add-on, which upkeep
installs into every environment automatically; you never have to invoke it
yourself, but you can:
| Command | What it does |
|---|---|
ddev upkeep-fixture-create <name> |
Dump the current database to a portable fixture and write its manifest. Runs drush sql:sanitize by default when the destination is the module repository; --no-sanitize opts out |
ddev upkeep-fixture-load <name> |
Load one. First use imports the dump; later loads restore a snapshot |
ddev upkeep-fixture-list |
Both scopes, with size and snapshot state |
ddev upkeep-fixture-prune |
Delete this project’s materialized snapshots — never the dumps |
Making one, start to finish
Section titled “Making one, start to finish”A worked example on helper for Drupal 11. Substitute your own module and core
major throughout.
1. Get a running site
Section titled “1. Get a running site”upkeep dev helper --version=11cd "$(upkeep env:path helper --version=11)"ddev launchdev provisions the environment if there is not one yet and prints where it
is. What you get is a clean minimal install of that core major with your module
linked in — the same thing every check runs against, which is the point: a
fixture captured anywhere else is a fixture that may not load here.
Two paths inside the environment are worth knowing, because they are the same files by two names:
| Path | What it is |
|---|---|
<project>/module |
your module’s git checkout — the real one, and where a commit goes |
<project>/web/modules/contrib/helper |
a symlink to it, which is where Drupal and the checks look |
2. Set the site up the way you want it captured
Section titled “2. Set the site up the way you want it captured”Either through the UI, after a one-time login link, or with drush directly:
ddev drush uliddev drush en helper -yOther contrib is allowed, and composer is what makes it travel. A
realistic fixture often needs more than the module under test — a workflow, a
field type, an admin UI — so install it the way the next environment will have
to:
ddev composer require drupal/admin_toolbarddev drush en admin_toolbar -yThe manifest is generated from the project’s own composer.json, so a package
required like that is recorded in the fixture’s require:, and
upkeep-fixture-load installs it for you in any environment that does not
have it. You are not limited to what your module depends on.
What does not travel is anything composer cannot fetch on the other side: a
custom module, a package from a private repository, or code copied into
web/modules/ by hand. That code is in your codebase and absent from
composer.json, so the manifest never learns of it, and the load is refused
with the extension named rather than failing later inside Drupal. If a fixture
has to carry something like that, the module it belongs to has to be in the
project by hand on every machine that loads it — which is usually the sign to
build the state with composer-installable code instead.
A dump alone is not enough is the mechanism in full.
3. Export it
Section titled “3. Export it”ddev upkeep-fixture-create smokeThat writes smoke.sql.gz and its generated smoke.yml manifest. You never
write the manifest; it is read out of the database and the project’s
composer.json at this moment, so it cannot drift from the dump beside it.
Where it lands: the module repository when the project root is a module checkout, the shared library otherwise. Say which if you would rather not rely on that:
ddev upkeep-fixture-create smoke --dest=module # tests/fixtures/ in the moduleddev upkeep-fixture-create smoke --dest=library # shared across modulesTwo things it does for you, both worth knowing about rather than discovering:
- It sanitises by default when the destination is the module repository —
drush sql:sanitize— because a committed fixture is public data.--no-sanitizeopts out, and the only database that deserves it is one that never held a real account or address. - It warns past 5 MB. A minimal install plus the entities you need gzips to well under that. Megabytes beyond it are usually cache and watchdog tables; truncate them and dump again.
4. Prove it loads before you rely on it
Section titled “4. Prove it loads before you rely on it”ddev upkeep-fixture-listupkeep check helper --working-copy --version=11 --fixture=smokeThe second line is the real test, because it is the thing that will consume the fixture from now on. An unknown name aborts before any check runs, so a typo cannot quietly test against the wrong state.
If the load is refused, the message names what is missing — a core-major mismatch, a package it installed, or an extension nothing can install for you (a custom module in the dump is the usual culprit).
5. Commit it, if it belongs to the module
Section titled “5. Commit it, if it belongs to the module”cd "$(upkeep env:path helper --version=11)/module"git add tests/fixtures/smoke.sql.gz tests/fixtures/smoke.ymlgit commit -m "Add a smoke fixture"Commit both files: a dump whose requirements nobody recorded only works on
the machine that made it. Never commit a snapshot — those are disposable local
caches, and .sql.gz plus .yml is the whole portable artifact.
A module fixture shadows a same-named library one, so this is how you give every co-maintainer the same state without them running upkeep at all.
Using it from then on
Section titled “Using it from then on”upkeep check helper 94 --fixture=smokeupkeep patch:check helper 3597857 --fixture=smokeThose two are the only commands that take --fixture; review, dev and
patch:apply do not. First use imports the dump and materializes a snapshot;
every later load restores the snapshot instead, which is most of why this is
worth doing.
When it goes stale
Section titled “When it goes stale”Re-create it under the same name — upkeep-fixture-create overwrites, and the
changed checksum invalidates the snapshot, so the next load rebuilds from the
new dump. If you only want the cache gone, ddev upkeep-fixture-prune or
upkeep prune deletes snapshots and never dumps.
A dump alone is not enough
Section titled “A dump alone is not enough”A database encodes references to code: which extensions are enabled, plugin IDs inside config entities, field types, schema versions. It captures none of that code. Load a dump into an environment that does not provide it and Drupal cannot build a container — and because that happens during your checks, the failure reads as though the merge request under test is broken.
That matters here more than on an ordinary site, because an upkeep environment is deliberately spare. It contains core, the module under test, that module’s own dependencies, and the check toolchain. Nothing else. So a fixture captured on your everyday development site, with whatever contrib you happen to have installed, will not load into one.
The dividing line is worth knowing:
| In the fixture’s database | In an upkeep environment? |
|---|---|
Core modules and themes — node, views, olivero, claro |
Yes, they ship inside drupal/core |
| The module under test, and its submodules | Yes |
Anything that module requires in its composer.json |
Yes — composer resolves it |
Any other contrib — admin_toolbar, webform, paragraphs |
No |
So olivero needs nothing, and admin_toolbar needs only to be in the
project’s composer.json when the fixture is captured — ddev composer require drupal/admin_toolbar is the whole difference between a fixture that installs
it on load and one that is refused. The restriction is not “only what your
module depends on”; it is “only what composer can fetch”.
This is what the manifest is for. upkeep-fixture-create records the core
version, the enabled extensions and the composer requirements it saw:
core: '11'core_version: '11.4.6'require: drupal/admin_toolbar: '^3.4'extensions: [admin_toolbar, node, pathauto, views]and upkeep-fixture-load makes the environment able to hold the dump, or
refuses before touching the database:
- Core major must match. A dump captured on Drupal 11 will not be loaded into a Drupal 10 environment.
- Declared packages are installed if the environment does not have them, and what it installed is printed. This is why the requirement has to live in the fixture rather than in your shell history: an environment can be re-provisioned at any time — a base-artifact rebuild does it through seed skew — and anything you added by hand goes with it.
- Every declared extension must then be present, or the load is refused and the missing ones are named. A custom module in a fixture is the case that lands here; nothing can install it for you.
You never write the manifest. It is generated from the database and the
project’s composer.json at capture time, so it cannot drift from the dump it
sits beside.
A dump with no manifest — one captured before they existed — loads exactly as it always did, with nothing checked.
Dumps and snapshots
Section titled “Dumps and snapshots”On first load the dump is imported and materialized into a fast-format snapshot, which later loads restore instead of re-importing. A metadata file records the database engine identity and the dump’s checksum at materialization time; if either changes — you upgraded the engine, or the dump was updated — the snapshot is stale and is rebuilt from the dump on the next load.
Snapshots are disposable, engine-tied local caches and never authoritative.
upkeep prune and ddev upkeep-fixture-prune delete them; the dump is untouched, and
the next load rebuilds. Do not commit them.
Where a fixture is found
Section titled “Where a fixture is found”Module scope first, then the shared library:
tests/fixtures/<name>.sql.gzin the module checkout — when the project root is a module checkout, which under ddev-drupal-contrib it is.- The shared library:
$UPKEEP_FIXTURE_LIBRARY, defaulting to<cockpit>/fixtures, defaulting to~/.upkeep/fixtures.
A module fixture always shadows a same-named library one. So a fixture committed to the module wins for everybody who checks that module out, and the library is for state you want across modules.
The tests/fixtures/ convention
Section titled “The tests/fixtures/ convention”This stands alone. It applies to any Drupal contrib module, whether or not you
or your co-maintainers use upkeep — anyone without the add-on can
gunzip -c tests/fixtures/<name>.sql.gz and import it with whatever they like.
- Path.
tests/fixtures/in the module repository, beside the module’s other test resources. - Format and naming. One gzipped SQL dump per fixture,
tests/fixtures/<name>.sql.gz, plus its generated manifest,tests/fixtures/<name>.yml. Commit both — a dump whose requirements nobody recorded is a dump that only works on the machine it was made on. Lowercase, filesystem-safe, and named for the state it provides:smoke.sql.gz,two-vocabularies.sql.gz,upgrade-from-2x.sql.gz. - Sanitisation is mandatory. A committed fixture is public data. Never dump
a database holding real accounts, e-mail addresses, personal data or secrets:
sanitise first, or build the fixture from a scratch install that never held
any.
ddev upkeep-fixture-createrunsdrush sql:sanitizefor you by default when the destination is the module repository. - Keep them lean. The minimum state that makes the fixture useful — a minimal-profile install plus the entities your tests need, not a production copy. Gzipped SQL of a minimal Drupal install is well under 5 MB; treat anything larger as a smell (the add-on warns at that threshold), and megabytes of it are usually cache and log tables. Truncate them before dumping.
The add-on itself
Section titled “The add-on itself”upkeep installs ddev-upkeep into every environment it provisions, at a pinned release — the same treatment ddev-drupal-contrib gets, and for the same reason: an environment that tracked whatever the latest release happened to be would take a breaking change to the add-on without warning. An environment holding an older release re-installs on next use.
To develop the add-on against upkeep, point it somewhere else:
export UPKEEP_ADDON_SOURCE=/path/to/ddev-upkeepThat takes a local checkout or anything ddev add-on get accepts, and no
version is pinned to it — a checkout has no release to pin to. Moving between
a checkout and the published release re-installs, so an environment cannot be
left holding whichever arrived first.