Last updated 28 June 2016.

On this page:

To get help completing this task, see the Getting help completing your task page.


Manually test a patch (software fix) for a reported Drupal issue to verify that it resolves the issue and does not cause other regressions (new bugs).

Skills needed

Some familiarity with the module, theme, or task is helpful, but not required. You will also need to apply a patch to a test site.

Detailed steps

  1. Install Git on your computer, if it is not already installed. See the installing git page for more information.
  2. Install Composer on your computer, if it is not already installed. See the Composer installation instructions for more information.
  3. If you don't have a Drupal site to test on, set up a local server. You probably do not want to use a live, production web site for this task.
  4. Install Drupal from Git on this local server. You will probably need to install the latest, in-development version of Drupal, as most testing and patching is done against that version (rather than the released version). For instructions on how to download Drupal from Git, see Drupal core version control instructions
  5. Install dependencies if you're working Drupal 8.1.x or higher you will need to run composer install in the Drupal root to install all dependencies.
  6. Find issues for a Drupal project (search core link).
  7. Choose an issue marked "Needs review." For Drupal core, use the advanced search to find an issue marked "Needs Review" and tagged with the "Needs manual testing" tag.
  8. Make sure you can reproduce the issue on your test site. (If the steps to reproduce the issue are unclear, you can document them or add a comment asking for clarification. If you cannot figure out how to reproduce the issue, choose a different issue.)
    • If the issue is related to a frontend bug or change (such as a theme modification, a CSS or JavaScript bugfix, or a change to a form), it can be helpful to take a screenshot of the behavior before the issue is fixed. (Contributor task: add screenshots has guidelines for good screenshots.)
    • If the patch for the issue includes changes to CSS or JavaScript, it will need to be tested in all supported web browsers for that version of Drupal. (Link here.) Try to reproduce the issue in as many supported browsers as are available to you.
    • For Drupal core, some frontend issues should also be tested in all core themes, including Bartik, Seven, Stark, and (for Drupal 7) Garland.
  9. Your task is now to test the most recent patch and verify that it resolves the issue and does not cause any new bugs.
    • Apply the patch to your local Drupal installation and clear the site cache. See the Background section below to find information about how to apply a patch.
    • Follow the steps to reproduce the issue with the patch applied. Confirm whether the issue is resolved by the patch.
    • If it is a frontend change, take a screenshot of the result with the patch applied.
    • If you are testing multiple browsers, note the result in each.
  10. Add a comment to the issue documenting the results of your testing.
    • Identify which browser(s) and theme(s) you used in your testing.
    • Explain the result in some detail (not just "the patch worked" or "the patch didn't work").
    • If you took screenshots, upload them as attachments to your comment, and embed them in the comment using an <img> tag.
    • If the patch does not fix the issue, or if it caused new bugs, set the issue status to "Needs work."
    • If the patch does resolve the issue and (if appropriate) has been tested in all supported browsers and/or all core themes, remove the "Needs manual testing" tag if it is present.

Background and reference information

Next steps: moving beyond this task

  • Manually test more issues in the same project or a different project, following the same steps as above.
  • Review the patch code.

Notes for reviewers

In general, follow the instructions for contributing as a reviewer and how to review patches. Keep in mind how to give constructive feedback.

Specific to this task:

  • Reproduce the issue before applying the patch.
  • Test after applying the patch to verify the fix.
  • Document the exact steps used to test the patch (a numbered list).
  • Indicate which browser/version and theme were used for testing.
  • Attach screenshots to the comment (cropped to only the relevant portion of the screen and embedded with an <code></code> tag).


YesCT’s picture

Video posted at #1776166-18: Improve default language negotiation and some follow up tips for speeding up the testing by Gabor at #1776166-20: Improve default language negotiation. There are some example screen shots in #1776166-16: Improve default language negotiation. Let's see if I can figure out a good flow and make a new video of (some of) the steps in this doc.

Another testing: This time, I used drush si to make installing the site faster and show taking some screenshots with jing. Being efficient is a work in progress.

YesCT’s picture

Addi's nice Drupal Ladder vid on patch testing: a free vid

Some thoughts that vid triggered on being efficient: some patches don't need a fresh install to test. Some can just be applied and a page reloaded, some maybe can have update.php run... what other categories are there? Some maybe need caches cleared, some might need a real clean install.

I wonder if a doc with tips for recognizing which are which is already on or on the Drupal ladder. Or if having the person posting the patch include that info would be a pattern that would be helpful.

(Perhaps a contributor task exists, like test a patch, but called: post in an issue the steps to test a patch.)

YesCT’s picture

The contributor task: document steps to reproduce a reported issue,
is pretty much what I mentioned (post in an issue the steps to test a patch).
In that, it advises starting from a clean install.

So it might be helpful to give ways of doing that efficiently (command line tricks, drush, etc), or ways of knowing when that is not necessary.

I think the main audience for the help docs like these is someone doing it for the very first time ever. So it's good: doing it clearly (but taking a little longer) and giving steps that are totally reproducible (fresh from scratch install). Maybe a follow-up doc for folks how are doing lots of testing (or lots of whatever task) could be written. Tips for doing task.