Drupal Testing: How to Test Drupal Websites
To test a Drupal website, you combine automated testing (PHPUnit for unit and functional tests, Behat for behavior-driven tests) with manual testing across browsers and devices, covering functionality, performance, security, and accessibility. This article explains the core testing layers, the tools Drupal provides out of the box, and a practical workflow you can apply to any Drupal site.
Why Drupal Testing Is Different
Drupal is a modular content management framework. A typical site combines dozens of contributed modules, custom code, and a database-driven configuration system. This means a change in one module can break something seemingly unrelated. Testing is not optional; it is the safety net that lets you update modules, add features, and refactor code without fear.
Drupal has built-in testing infrastructure that is more advanced than most CMSs. Since Drupal 8, it uses PHPUnit, the industry-standard testing framework, and provides a core/tests directory with thousands of tests. The Testing module (core) gives you a UI to run tests, and Drush provides command-line access. You can write tests that simulate a full browser request, test database interactions, or test a single function in isolation.
Types of Tests You Need
Different levels of testing catch different problems. A complete strategy uses all of them.
- Unit tests – test a single class or function in isolation, with no database or web server. They are fast and run in milliseconds. Use them for custom modules, services, and helper functions.
- Kernel tests – boot Drupal with a test database but no full HTTP request. They are useful for testing database queries, entity validation, and services that need the database.
- Functional tests (BrowserTestBase) – simulate a real browser session using Mink and a built-in HTTP client. They create a fresh Drupal installation in a test database, so they are slow but realistic. Use them to test user workflows, permissions, and form submissions.
- JavaScript tests – test client-side behavior using Nightwatch.js (built into Drupal core) or Cypress. These are for interactions like AJAX autocomplete, custom JS, or complex UI states.
- Behavior-driven tests (Behat) – write scenarios in plain English (Gherkin) that map to automated steps. They are great for acceptance testing and for communicating with non-technical stakeholders.
- Manual testing – exploratory testing by a human, especially for visual layout, cross-browser issues, and usability. Automated tests cannot catch everything.
Drupal’s Built-in Testing Tools
Drupal core ships with a testing framework that you can enable via the Testing module (core). Once enabled, go to /admin/config/development/testing to see a list of all available tests. You can run a single test class or a group. The output shows pass/fail, errors, and backtraces.
For command-line testing, use phpunit directly from the Drupal root. The core PHPUnit configuration is in core/phpunit.xml.dist. Copy it to phpunit.xml and set the SIMPLETEST_BASE_URL and SIMPLETEST_DB environment variables to point to a test database. Then run:
vendor/bin/phpunit -c core --testsuite unit
vendor/bin/phpunit -c core --testsuite functional
Drush also has commands like drush test-run that wrap PHPUnit. For JavaScript, Drupal core includes core/package.json with Nightwatch.js. Run yarn test:nightwatch after setting up the WebDriver.
Setting Up a Testing Environment
You need a separate test database and a web server that can serve the site. The test runner creates a fresh installation for each functional test, so the database credentials must have permission to create and drop databases. A typical setup uses:
- PHP 8.1 or higher, with the
pdo_mysqlorpgsqldriver - Composer to install dependencies
- A local web server (Apache, Nginx, or PHP’s built-in server)
- MySQL or PostgreSQL for the test database
- ChromeDriver or Selenium for JavaScript tests
For continuous integration, use GitLab CI, GitHub Actions, or Jenkins. A simple CI pipeline runs unit tests, then kernel tests, then functional tests, and finally JavaScript tests. Each stage runs on a clean environment to ensure reproducibility.
Writing Your First Test
Suppose you have a custom module called mymodule with a function that returns a greeting. A unit test would look like this:
namespace Drupal\Tests\mymodule\Unit;
use Drupal\Tests\UnitTestCase;
class GreetingTest extends UnitTestCase {
public function testGreeting() {
$greeting = new Greeting();
$this->assertEquals('Hello, World', $greeting->get('World'));
}
}
Place the file in mymodule/tests/src/Unit/GreetingTest.php. Run it with vendor/bin/phpunit -c core --testsuite unit modules/mymodule/tests.
For a functional test that checks a user can log in, extend BrowserTestBase and use methods like $this->drupalGet(), $this->submitForm(), and $this->assertSession(). These methods simulate a real browser session and verify the HTML response.
Common Testing Pitfalls
Even experienced developers make these mistakes:
- Not isolating tests – tests should not depend on each other. Each functional test gets a fresh install, but unit tests must not rely on global state.
- Using the production database – never run tests against a live database. Use a dedicated test database that can be wiped.
- Ignoring test speed – functional tests are slow. Keep them focused on critical paths, and use unit tests for logic.
- Skipping JavaScript tests – if your site has any custom JS, you need browser-level tests. A PHP-only test will not catch a broken AJAX call.
- Not testing configuration – Drupal’s configuration management system can be tested by exporting and importing config in a test environment. This catches missing dependencies.
Manual Testing and Accessibility
Automated tests cannot replace a human. You should manually test:
- Responsive layout at common breakpoints (mobile, tablet, desktop)
- Forms with keyboard navigation and screen readers
- Cross-browser behavior (Chrome, Firefox, Safari, Edge)
- Real user flows like registration, checkout, or content editing
For accessibility, use automated tools like axe (via the Accessibility Testing module) and then manually test with a screen reader. Drupal core has a core/misc/announce.js that helps with live regions, but you still need to verify your custom themes and modules meet WCAG 2.1 AA.
Frequently Asked Questions
What is the difference between BrowserTestBase and WebTestBase?
WebTestBase is the older base class from Drupal 7/8, based on SimpleTest. It is deprecated in Drupal 9 and removed in Drupal 10. BrowserTestBase is the modern replacement, built on PHPUnit and Mink. Always use BrowserTestBase for new tests.
How do I test Drupal migrations?
Drupal’s migrate API provides a test framework. You can use MigrateTestCase to test your custom migration plugins. For full migration tests, use KernelTestBase with the migrate modules enabled and a source database configured.
Can I test Drupal without a database?
Yes, unit tests do not touch the database. They only test PHP classes in isolation. Kernel tests need a database, but you can use SQLite for local development to avoid setting up MySQL.
How do I test a Drupal site’s performance?
Performance testing is separate from functional testing. Use tools like Apache JMeter, k6, or Siege to simulate load. For profiling, use Xdebug or the Web Profiler module. Drupal’s built-in testing framework does not measure performance.
What is the best way to test a Drupal 7 site?
Drupal 7 uses SimpleTest, not PHPUnit. You can run tests via the Testing module UI or with drush test-run. For new work, consider upgrading to Drupal 10, as Drupal 7 reached end-of-life in January 2025.
How do I test a Drupal site’s security?
Use the Security Review module to scan for common misconfigurations. For penetration testing, use tools like OWASP ZAP or Burp Suite. Automated tests can check for SQL injection, XSS, and CSRF vulnerabilities by sending malicious input and verifying the site does not execute it.
Related
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.