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 execute 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.
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.
Maybe you've heard of anonymous closures but you're not quite sure how they apply in Drupal, or why using them is considered a best-practice. Anonymous closures allow you to avoid accidentally clashing with anything in the global scope, as well as to alias the jQuery object to the more commonly used $
. This is necessary because Drupal runs jQuery in no-conflict mode. This tutorial will look at the syntax used for placing your custom JavaScript code inside an anonymous closure, and why it's a good idea to do so.
In this tutorial we'll:
- Explain what a closure is (briefly), and what immediately invoked function expressions are
- Show how typically Drupal JavaScript gets wrapped in a closure
- Provide a copy/paste example you can use in your own code
By the end of this tutorial you should be able to explain what an anonymous closure is, and how to use one in your custom JavaScript for Drupal.
Drupal Console
FreeThe Drupal Console is a suite of tools run from a command line interface (CLI) to generate boilerplate code and interact with a Drupal installation.
Note: This project is no longer actively maintained. See the Drush topic for alternative solutions.
In this tutorial, we'll walk through the process of adding and configuring filters and adding a filter group.
In this tutorial, we'll walk through the process of adding and configuring sort criteria to a view.
In this tutorial, we'll add and configure a contextual filter for a view. Our Baseball Awards content type has a field Year. We'll make it possible for a page to be dynamically created on our site that contains the year and lists the awards for that specific year. To do this, we'll add a contextual filter to the Baseball Awards view that will allow visitors to filter the list of awards by the award year. We'll also add a block using the summary view contextual filter configuration, which visitors can use to view results for specific years.
One of the ways you can create a REST endpoint in Drupal is by using Views. In this tutorial, we'll add a REST endpoint display to a view of baseball players. We'll examine and configure settings that are unique to the REST endpoint display.
By the end of this tutorial you should be able to:
- Add a REST endpoint display to a view
- Understand how to configure settings for an endpoint
Instead of providing multiple views with different filter criteria, consider empowering your users by exposing filter criteria as an interactive form. You can even configure the forms to use AJAX to refresh results. In this tutorial, we'll walk through the process of adding and configuring exposed filter or sort criteria in a view.
Like exposed filters, we can expose sort criteria to the site visitor. Exposing sort criteria gives the visitor more control over the list of content they are viewing. In this tutorial, we'll configure our view of baseball players to allow visitors to sort the list in different ways by adding several exposed sort criteria.
Contextual filters are a Views mechanism for dynamically refining the contents of a view. It might be helpful to think of them as "dynamic filters". In this tutorial, we'll discuss the concept of context, look at how to add contextual filters in the Views UI, and review the Taxonomy term view that comes with Drupal and how it uses a contextual filter.
Exposing filter criteria allows the users of your site to choose how to filter a content list created in Views. When rendered on the page, the exposed filters will be displayed to the user as interactive form components.
By the end of this tutorial you will:
- Understand what it means to expose filter criteria and when it might be useful.
- Be able to identify when a view has exposed filters and which filters are exposed.
Exposing sort criteria allows the users of your site to sort a view using an interactive form.
By the end of this tutorial you will:
- Understand what it means to expose sort criteria and when it might be useful.
- Be able to identify a view's exposed sort criteria.
With filters, we can define query conditions and refine the results of a view. But what is a filter and how do filters work in Views? In this tutorial, you'll learn:
- How to add and configure filter criteria to a view to refine results
- What configuration options are available for filter criteria operators
- How filter groups allow you to group and order filter criteria to achieve desired results
By the end of this lesson, you should understand how to use and configure filter criteria in Views to refine the results of your view. (Note: We'll cover exposed filters in Overview: Exposed Filter Criteria in Views)
In order to display values for referenced entities in views, you need to add a relationship. What is a relationship, how do they work, and what does it mean to require this relationship? What are some common use cases for adding a relationship to a view? By the end of this tutorial you should be able to:
- Explain some common use cases for adding a relationship to a view.
- Understand the concept of entity references and how those field values can be displayed in a view.
With sort criteria, we can specify how to order our list. We can specify sort criteria using any field on or related to our view's base entity, and then specify in which order to sort, e.g. ascending or descending. If you are familiar with MySQL, it may be helpful to know that sort criteria are the ORDER BY
clause of the query that Views builds. In this tutorial, you'll learn:
- How to add and configure sort criteria to a view to sort the list in various ways
- What configuration options are available
By the end of this lesson, you should understand how to use and configure sort criteria in Views. (Note: We'll cover exposed sort criteria in Overview: Exposed Sort Criteria in Views)
Like most output in Drupal, Views relies on Twig templates for a significant amount of its rendering. In this tutorial we'll identify where you can find the default Views templates within your file system, what the common templates are for, and how to name your templates so that they are applied to specific views.
By the end of this tutorial, you should be able to:
- Identify where to find default views templates
- Understand which templates apply to what part of a view
- Get a sense of the template suggestions and how to use them to limit where your custom templates are applied
- Identify a view's machine name
- Identify a display's machine name
- Identify a field's machine name
Now that you understand the purpose of relationships in Views, let's add a relationship to a view so that we can access and display a field value from a related entity.
In this tutorial, we'll modify the Player Awards view to add a relationship to the player that received the award. Then we will add a field that belongs to the player content that would normally not be available to the view without our new relationship.