How to write test cases for Drupal project

Drupal supports multiple test layers. Use each layer where it makes sense.

• Unit tests — fast tests that check a single class or function in isolation; they do not boot Drupal.
• Kernel tests — boot a part of Drupal (database, entity system) without a full HTTP stack.
• Functional tests — test Drupal through its APIs with a simulated request environment; good for testing routing, forms, and entity flows.
• Functional JavaScript / Browser tests — run full browser-like scenarios including JS; useful for interactive UIs.
• SimpleTest legacy tests — older style; most projects now use PHPUnit-based tests.- Integration tests — mix of unit and kernel ideas; often custom for complex integrations.

Setting up PHPUnit properly makes writing test cases and running tests straightforward.

1. Install dev dependencies

Use Composer to require testing tools: PHPUnit and Drush (if needed) as dev dependencies.

2. Use Drupal core’s testing scaffold

Drupal core includes testing bootstrap files and recommended phpunit.xml.dist that you can copy and customize.

3. Configure phpunit.xml

Copy phpunit.xml.dist to phpunit.xml and set database credentials, temp directories, and test group settings.

4. Provide a test database

Create a separate test database or configure SQLite for quick tests. Ensure tests run on a disposable DB to avoid data loss.

5. Configure settings.php for tests

Use settings.testing.php or add overrides in phpunit.xml for temporary storage, file paths, and services.

6. Run a smoke test

Run a single test class using vendor/bin/phpunit to verify that the environment is functioning properly.

Once complete, you can run focused tests during development and the entire suite in continuous integration.

• Namespace: follow PSR-4 under tests/src/Unit in your module.
• Class extends PHPUnit\Framework\TestCase.
• Use small, focused test methods: testMethodDoesX.- Mock dependencies with PHPUnit mocks or prophecy.

Example (conceptual)

• Test a service method that calculates totals.
• Mock repository or external service to return fixed data.
• Assert that your service returns expected totals and handles edge cases.

Tips for unit tests

• Test one behavior per test method.
• Use data providers for similar cases.

Writing functional tests

• Place tests in tests/src/Functional or tests/src/FunctionalJavascript.
• Extend appropriate base classes (e.g., BrowserTestBase, JavascriptTestBase).
• Use setUp() to install required modules and create test content.
• Use drupalGet(), submitForm(), and assertSession() helpers to interact and assert.

Example flow

• Log in as a user with specific permissions.
• Visit a content creation form.
• Fill and submit the form.
• Assert that the node exists and contains expected text.

When to choose browser tests

• When JavaScript behaviour matters.
• When you need to validate full UI flows (forms, AJAX, progressive enhancements).

Browser tests are slower; use them for critical flows and complement them with many unit tests.

• For kernel/functional tests, use Drupal’s service container overrides:  
• In tests, use $this->container->set(‘service_name’, $mock) or use settings.service_overrides in settings.testing.php.
• When mocking external HTTP calls, abstract calls behind an interface and mock that interface.
• For config and state, inject a config factory or state service and provide test doubles when needed.

Mock thoughtfully: mock behaviour you control, not trivial getters. The goal is to test your code, not Drupal internals.

1. Choose CI platform

Use Jenkins or GitHub Actions or GitLab CI, or CircleCI.

2. Create a reproducible environment

Use Docker images with PHP, Composer, and required extensions or a ready-made Drupal CI image. To know more details about refer link, how to create a docker base setup for drupal

3. Install dependencies

Run composer install –no-interaction –prefer-dist –no-progress.

4. Set up test DB and files

Use a fresh database and writable files directory for each job.

5. Run selected tests

On pull requests, run quick unit tests and a few kernel tests. 

On the main branch or nightly, run the full test suite, including functional and JS tests.

6. Parallelize

Split tests into groups to run in parallel jobs and reduce total CI time.

7. Report results

Fail pipeline on test failures and show clear logs. Use Junit output so the CI UI displays failing tests neatly.

CI keeps your team fast and confident. Aim for fast feedback by running the fastest, highest-value tests first.

• Place tests in module/tests/src/{Unit, Kernel, Functional, FunctionalJavascript}.
• Name test classes clearly: ModuleNameFeatureTest or ServiceNameTest.
• Keep tests small and focused.
• Use one assertion per logical outcome; grouping multiple assertions is okay when they belong to the same action.
• Avoid testing Drupal internals; test your module’s behaviour.
• Seed test data in setUp using minimal entities; prefer factories or builders to avoid duplicated code.
• Use data providers for parametrized tests.
• Group slow tests and mark them so they don’t run on every push.
• Keep helper methods in a TestTrait when reused across test classes.
• Document non-obvious test flows with brief comments.

Organize tests like production code: easy to find, easy to run.

Example: A simple unit test flow for a custom service

1. Identify the service method behavior you want to test.

2. Create a tests/src/Unit/ServiceNameTest.php file.

3. Mock repository and external dependencies.

4. Call the method and assert the output and side effects.

5. Run vendor/bin/phpunit –filter ServiceNameTest.

This tight loop (write test, run, fix code) speeds up development and prevents regressions.

Example: A functional test flow for a content workflow

1. Create tests/src/Functional/ContentWorkflowTest.php extending BrowserTestBase.

2. Install required modules and create a test user in setUp().

3. Use $this->drupalLogin() to authenticate.

4. Visit content add path, fill form with $this->submitForm(), and check redirect.

5. Assert that the node was created and published or has expected fields. Functional tests give confidence that the site behaves correctly for real users.

• Prioritize unit tests because they are fast and provide high coverage of the logic.
• Add kernel tests where entity and schema interactions matter.
• Add functional/browser tests for critical user flows and integrations.
• Mark and run slow tests less frequently (nightly or pre-release).

• Over-mocking — mock only what you control; prefer integration tests when behavior depends on Drupal internals.
• Tests depending on order — make each test independent.
• Long setup in tests — reuse minimal required setup or use lightweight fixtures.
• Ignoring flaky tests — address flakiness immediately; flaky tests erode trust.

Fix test environment issues first; they are the most common source of developer frustration.

• Track test execution time and flakiness.
• Remove redundant or obsolete tests.
• Review failing tests with each PR.

• PHPUnit — core test runner for almost all tests.
• Behat / Mink — an alternative for higher-level acceptance tests.
• PHP-mock / Prophecy — for more advanced mocking needs.
• Drupal’s testing traits and helpers — use the provided helpers for common tasks.

Use tools that fit the team and the project scale.

• Drupal Unit tests written for new logic.
• Kernel tests added for DB or entity interactions.
• Functional tests included for new user-facing flows or forms.
• No direct edits to production configuration in tests.
• CI jobs updated to run relevant test groups.
• Tests run locally and pass.