Choose a Drupal test by the behavior you need to verify: use a unit test for isolated logic, a kernel test when it depends on Drupal services or a limited Drupal environment, a functional test for routes and rendered behavior, and a functional JavaScript test when browser-side JavaScript or Ajax matters. These layers complement one another; none replaces the rest.
Which Drupal test should I write?
Start at the lowest layer that can reliably exercise the behavior. A focused test is generally simpler to set up; move toward a fuller Drupal or browser environment only when the behavior requires it.
| Test type | Use it for | Drupal environment | Real browser? |
|---|---|---|---|
| Unit | Isolated class behavior | Minimal dependencies; no working Drupal installation required | No |
| Kernel | Behavior that needs Drupal services, entities, or a limited set of extensions | Bootstrapped kernel; requires a database connection | No |
| Functional | Routes, permissions, forms, rendered output, and complete-installation behavior | Full Drupal instance reachable through a web server | No. It simulates browser behavior, but does not exercise actual JavaScript or Ajax interaction. |
| Functional JavaScript | JavaScript and Ajax behavior as it runs in a browser | Drupal test environment plus WebDriver setup | Yes |
This four-part taxonomy is documented by Drupal.org in Types of tests. Drupal describes its broader testing goal as covering all or most components and features and running automated tests before changes to catch regressions; see the Drupal API documentation on automated tests.
Unit tests: isolate the logic
Use PHPUnit tests based on DrupalTestsUnitTestCase when the class or method can be checked with minimal dependencies. This is a good fit for calculations, transformations, and decision logic that does not need Drupal’s service container or a database.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
#1 Best Overall
Kernel tests: bring up only the Drupal pieces needed
Use DrupalKernelTestsKernelTestBase when the behavior relies on Drupal services, the entity system, or selected extensions, but not on a full site served to a browser. Kernel tests require a database connection.
Functional tests: check integrated Drupal behavior
Use DrupalTestsBrowserTestBase for behavior involving a full booted Drupal site, such as access permissions, routes, forms, and rendered pages. These tests exercise web output through Drupal’s browser-test machinery, but they are not JavaScript or Ajax tests running in a real browser.
Functional JavaScript tests: verify browser-side behavior
Use DrupalFunctionalJavascriptTestsWebDriverTestBase when the result depends on JavaScript or Ajax. These tests use WebDriver to interact with a real browser, so their setup is heavier than a non-JavaScript functional test.
How do I choose a practical mix?
- Can the behavior be tested without Drupal? Write a unit test.
- Does it need Drupal services, entities, or a few extensions? Use a kernel test.
- Does the assertion concern a route, permission, form, rendered output, or complete site? Use a functional test.
- Does the expected result depend on JavaScript or Ajax? Use a functional JavaScript test.
- Is the workflow broader or more scenario-oriented? Consider a browser-testing tool or readable scenario framework described below, while retaining tests at the other layers for the behaviors they cover well.
Keep the mix proportionate to the code: isolated behavior is usually more direct to test at the unit layer, while a smaller number of integrated checks can protect critical user journeys. A higher-level test does not make lower-level tests redundant, and a unit test cannot establish that a complete browser workflow works.
Where do Cypress, Nightwatch, and Behat fit?
Drupal documentation also discusses Cypress browser testing, Nightwatch JavaScript testing, performance testing, and Behat scenarios. These are additional approaches, not interchangeable names for the four PHPUnit test types.
- Cypress: consider it for browser-level testing workflows where that tool fits the project.
- Nightwatch: consider it for JavaScript and browser testing; Drupal’s testing guidance also points to DDEV Selenium Standalone Chrome for core PHPUnit and Nightwatch testing.
- Behat: consider it when readable Gherkin scenarios suit the team and the behaviors being described.
- Performance testing: use it when the question is how the site performs under relevant conditions, rather than whether a single functional assertion passes.
Drupal’s documentation lists these options, but they do not suit every project or replace one another in every context. Review the relevant Drupal automated testing documentation before choosing a workflow.
Rank #3
How do I run PHPUnit tests?
Exact commands and configuration depend on the Drupal, PHP, PHPUnit, database, and local-development-tool versions in your project. The Drupal guide to running PHPUnit tests was updated July 17, 2026. Consult it alongside the guide to PHPUnit in Drupal rather than copying a command or dependency version without checking compatibility.
Check the configuration location first
By default, PHPUnit reads phpunit.xml from the current directory. You can supply another configuration file when running PHPUnit. Keep project-specific configuration somewhere Composer-managed core updates will not overwrite: Drupal notes that a phpunit.xml stored inside the core/ directory may be overwritten when updating core.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsMatch the environment to the test
- Unit tests: can run without a working Drupal installation.
- Kernel tests: need a database connection.
- Browser tests: need Drupal reachable through a web server.
- Functional JavaScript tests: also need a working WebDriver/browser setup.
For PHPUnit v9 configurations used with Drupal 10 and below, the running-tests guide documents settings including SIMPLETEST_BASE_URL, SIMPLETEST_DB, and BROWSERTEST_OUTPUT_DIRECTORY. Do not assume those settings or version guidance apply unchanged to another Drupal or PHPUnit combination.
Use version-matched setup instructions
Drupal’s guide points to DDEV add-ons for PHPUnit workflows and DDEV Selenium Standalone Chrome for core PHPUnit and Nightwatch testing. Before installing dependencies or adapting a command, verify the requirements for your project’s Drupal and PHP versions, PHPUnit version, database, and DDEV setup in the current official documentation. The documentation’s examples are configuration guidance, not a universal command set for every project.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.How can screenshot capture help when testing a Drupal site?
A screenshot is useful as a visual artifact for checking or recording rendered output, but it is not a substitute for the Drupal test layer that verifies the behavior. A captured image alone cannot establish that permissions, server-side logic, or JavaScript interactions work correctly.
For teams that need a screenshot of a page as part of a development workflow, ScreenshotNeo is a website screenshot API and MCP server. It can capture PNG, JPEG, WebP, or PDF; its capture options include full-page screenshots, selector-based element capture, custom CSS or JavaScript, and waiting for a selector, delay, or network idle. These capabilities support visual inspection, not assertions that replace PHPUnit or browser tests.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Best Value
- 5 beloved beginner books by Dr. Seuss will be cherished by young & old alike.
- Ideal for reading aloud or reading alone.
- Includes: The Cat in the Hat, One Fish Two Fish Red Fish Blue Fish, Green Eggs and Ham, Hop on Pop and Fox in Socks.
- Perfect gift for new parents, birthday celebrations & happy occasions of all kinds.
Or skip the browser setup
Make a screenshot request with the URL you want to capture; the API documentation lists the available parameters and response behavior at ScreenshotNeo API docs.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpScreenshotNeo accepts cookie or consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed; the response reports the page verdict and billing status in headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for AI agents using Claude, Cursor, or another MCP client. The free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.
Quick Recap
Common setup problems and what to check
- PHPUnit does not use the configuration you expected: check the current working directory. PHPUnit reads
phpunit.xmlthere unless another configuration is supplied. - A core update changes or removes your test configuration: check whether
phpunit.xmlwas stored insidecore/; Drupal warns that Composer-managed core updates may overwrite it. - A kernel test cannot connect to its database: confirm the database connection and test configuration. Kernel tests require a database connection.
- A browser test cannot reach the site: verify that the Drupal instance is reachable through a web server and that the base URL configuration matches the environment.
- A test involving JavaScript passes without exercising the interaction: confirm that it is a functional JavaScript test using WebDriver, not a non-JavaScript functional test.
- A documented setting or command does not fit the project: re-check the Drupal, PHP, PHPUnit, database, and DDEV versions against Drupal’s current running-tests guide. The cited environment variables are specifically documented for PHPUnit v9 configurations used with Drupal 10 and below.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Recommended Free Tools
