Previously, in Implement a Functional Test, we learned how to tell BrowserTestBase
to use the Standard installation profile in order to get our test passing, letting the Standard profile implicitly provide our dependencies. We mentioned that doing so probably wasn't the best decision and that we should explicitly declare those dependencies instead.
In this tutorial, we'll walk through how to explicitly declare our test's dependencies. When in doubt, it's generally considered a best practice to be as explicit about the dependencies of our tests as possible. By the end of this tutorial, you should be able to:
- Understand why we want to explicitly declare our dependencies.
- Determine what the dependencies really are and make a list of them.
- Implement each dependency in our list.
- Emerge with a thorough passing test.
In this tutorial, we'll walk through the basics of how to implement a functional test by extending Drupal's BrowserTestBase
class. We'll assume you've already determined that you need to write a functional test and that you've Set up a Functional Test.
In this tutorial, we'll:
- Determine the specifications of the test.
- Walk through the behavior we want to test.
- Document our test in the test class.
- Implement the testing steps.
- Decide how to deal with dependencies (for now). (We'll go into details about handling test dependencies in Implement Drupal Functional Test Dependencies.)
Let's write somewhat strict unit tests in a Drupal module. By the end of this tutorial, you will be able to:
- Understand what makes a unit test different from other types of tests.
- Determine the specifications of a unit test.
- Use mocking to isolate units under test, and to force code flow to achieve high coverage.
We'll start out with a brief introduction to unit tests. Then we'll look at a contrived example of a Drupal controller class for illustration purposes. Next, we'll test two units of this controller class, each requiring different mock styles.
In this gentle introduction to testing, we'll walk through what testing is and why it's important to your project. Then we'll define some terms you'll be likely to see while working with tests so that we're all on the same page. After reading through this tutorial you'll understand enough of the basic vocabulary to get started running (and eventually writing) tests for your Drupal site.
The testing suite for the Drupalize.Me site uses a different strategy for functional JavaScript testing. We use a tool called Nightwatch.js that allows us to write our tests in JavaScript that runs commands against a web browser. This browser automation allows us to test the types of interactions that a typical user of our website might encounter. It also allows us to test JavaScript code using JavaScript, and execute our tests in different browsers. In this tutorial we'll take a look at how to set up Nightwatch.js, and what the syntax looks like for a couple of basic tests.
In order for Drupal to be able to locate and run the tests you create, the files need to be put in the correct place. In this tutorial, we'll take a look at the different types of test frameworks that are included along with core. We'll also see how Drupal expects our test files to be organized so that the test runners can find them.
When running tests with PHPUnit we need to specify a phpunit.xml file that contains the configuration that we want to use. Often times (and in much of the existing documentation) the recommendation is to copy the core/phpunit.xml.dist file to core/phpunit.xml and make your changes there. And this works fine, until something like a composer install
or composer update
ends up deleting your modified file. Instead, you should copy the file to a different location in your project and commit it to your version control repository.
In this tutorial we'll:
- Learn how to move, and modify, the phpunit.xml.dist file provided by Drupal core
- Understand the benefits of doing so
- Demonstrate how to run
phpunit
with an alternative configuration file
By the end of this tutorial you should be able to commit your phpunit.xml configuration file to your project's Git repository and ensure it doesn't get accidentally deleted.
In this tutorial, we'll run tests in several different ways using the PHPUnit tools available in Drupal. We'll learn about various environment variables you'll need to supply to the test runner depending on which type of test you're running. And we'll learn various ways to get reports on the test results. By the end of this tutorial, you should understand how to run Drupal tests using PHPUnit.
Drupal core comes with a run-tests.sh script to help with running tests. This script has some distinct advantages over running tests directly via PHPUnit. It runs all tests in their own separate process, and can therefore handle PHP fatal errors without killing the test run. It's also the mechanism that the Drupal CI tools use to run tests; so, it can be handy when debugging tests that are failing on Drupal.org.
In this tutorial we'll:
- Look at the available options for the core run-tests.sh script
- Go through some examples of running tests using run-tests.sh
By the end of this tutorial you'll know how to run your tests using run-test.sh.
In this tutorial, we'll walk through the process of setting up a functional test. Then, we'll learn how to run it using two different test runners. This setup process allows us to be sure we're not getting false positives from the test runners. We'll be working on a functional test, but these techniques apply with minimum modification to all the Drupal PHPUnit-based tests.
By the end of this tutorial, you should be able to set up and run functional tests in Drupal using two different test runners.
This tutorial will clarify some basic ideas about software testing. We'll give some strategies for testing and illustrate types of tests and when and why you'd use them. This document is written with Drupal in mind, but the concepts apply for other development environments you'll encounter as well. The tools will be different, but the ideas apply universally. By the end of this tutorial, you should understand what testing is for and how different types of tests support different purposes and outcomes.
In order to run functional tests that require JavaScript be executed for the feature to work, the tests need to be run in a browser that supports JavaScript. This is accomplished by using the WebDriver API in combination with an application like ChromeDriver or Selenium, which can remotely control a browser.
The exact setup for running functional tests is dependent on your development environment. We'll walk through a couple of common examples including using Docker (via DDEV) and stand-alone applications.
In this tutorial we'll:
- Learn how to install and run ChromeDriver and other necessary tools either in a Docker environment, or locally.
- Configure the relevant PHPUnit environment variables so they contain values appropriate for our specific environment.
- Execute Drupal's functional JavaScript tests via the
phpunit
command.
By the end of this tutorial you should be able to install the applications required to run functional JavaScript tests in a browser, and know how to configure PHPUnit to make use of them.
Every theme can contain an optional THEMENAME.theme file. This file contains additional business logic written in PHP and is primarily used for manipulation of the variables available for a template file, and suggesting alternative candidate template file names. Themes can also use this file to implement some, but not all, of the hooks invoked by Drupal modules.
In this tutorial we'll learn:
- The use case for THEMENAME.theme files, and where to find them
- The different types of functions and hooks you can implement in a THEMENAME.theme file
By the end of this tutorial you should be able to know how to start adding PHP logic to your custom theme.
Themes and modules can alter the list of theme hook suggestions in order to add new ones, remove existing ones, or reorder the list. This powerful feature allows for the definition of custom logic in your application that can tell Drupal to use different templates based on your own unique needs. You might for example; use a different page template for authenticated users, or a custom block template for someone's birthday.
In this tutorial we'll cover:
- Adding new theme hook suggestions from a theme using
hook_theme_suggestions_HOOK_alter()
- Altering the list of theme hook suggestions
- Removing theme hook suggestions
- Reordering the list of theme hook suggestions
Underscore.js is a very small library which provides several utility functions and helpers to make working with JavaScript a little bit easier. In this tutorial we'll take a look at a part of the library, learn where the full library is documented, and see how we can make use of Underscore.js in a custom block on our Drupal site.
Make your theme a subtheme of a base theme, allowing it to inherit all the base theme's templates and other properties. When creating Drupal themes it is common to use the Classy theme provided with Drupal core as a base theme to jumpstart your development.
In this tutorial we'll learn how to:
- Use the
base theme
key in our theme's THEMENAME.info.yml file - Make our Ice Cream theme inherit from the Classy theme, or any other theme
By the end of this tutorial you should be able to tell Drupal that your theme is a child of another theme and should inherit all of the parent theme's features.
In Drupal, whenever we output markup it's best practice to use a Twig template or a theme function. But whenever you need to output DOM elements within JavaScript the best practice is to use the Drupal.theme
function. This function ensures that the output can be overridden just like the HTML output by Twig. This tutorial covers how to use the Drupal.theme
function in your JavaScript when inserting DOM elements, as well as how to replace the markup output by other JavaScript code that is using the Drupal.theme
function.
ESLint is the linting tool of choice for JavaScript in Drupal. In this tutorial we’ll show how to install the ESLint application and then use it to verify that your JavaScript files are meeting the Drupal coding standards.
Drupal (as of version 8.4) has adopted the Airbnb JavaScript coding standards. In this tutorial, we'll walk through how to install the necessary package dependencies to run eslint on JavaScript files within your Drupal site.
An asset library is a bundle of CSS and/or JavaScript files that work together to provide a style and functionality for a specific component. They are frequently used to isolate the functionality and styling of a specific component, like the tabs displayed at the top of each node, into a reusable library. If you want to include CSS and/or JavaScript in your Drupal theme or module you'll need to declare an asset library that tells Drupal about the existence, and location, of those files. And then attach that library to a page, or specific element, so that it gets loaded when needed.
In this tutorial we’ll:
- Define what an asset library is.
- Explain why asset libraries are used to include JavaScript and CSS files.
- Look at some example asset library definitions.
By the end of this tutorial you should be able to define what asset libraries are, and when you'll need to create one.
Preprocess functions allow Drupal themes to manipulate the variables that are used in Twig template files by using PHP functions to preprocess data before it is exposed to each template. All of the dynamic content available to theme developers within a Twig template file is exposed through a preprocess function. Understanding how preprocess functions work, and the role they play, is important for both module developers and theme developers.
In this tutorial we'll learn:
- What preprocess functions are and how they work
- The use case for preprocess functions
- The order of execution for preprocess functions
By the end of this tutorial you should be able to explain what preprocess functions are and the role they play in a Drupal theme.