woocommerce/tests/README.md

WooCommerce Tests

This document discusses unit tests. See the e2e README to learn how to setup testing environment for running e2e tests and run them.

Table of contents

• WooCommerce Unit Tests
  • Initial Setup
  • Running Tests
  • Writing Tests
  • Automated Tests
  • Code Coverage
• WooCommerce E2E Tests

Initial Setup

From the WooCommerce root directory (if you are using VVV you might need to vagrant ssh first), run the following:

1. Install PHPUnit via Composer by running:

   $ composer install
   

2. Install WordPress and the WP Unit Test lib using the install.sh script:

   $ tests/bin/install.sh <db-name> <db-user> <db-password> [db-host]
   

You may need to quote strings with backslashes to prevent them from being processed by the shell or other programs.

Example:

$ tests/bin/install.sh woocommerce_tests root root

#  woocommerce_tests is the database name and root is both the MySQL user and its password.

Important: The <db-name> database will be created if it doesn't exist and all data will be removed during testing.

Running Tests

Change to the plugin root directory and type:

$ vendor/bin/phpunit

The tests will execute and you'll be presented with a summary.

You can run specific tests by providing the path and filename to the test class:

$ vendor/bin/phpunit tests/legacy/unit-tests/importer/product.php

A text code coverage summary can be displayed using the --coverage-text option:

$ vendor/bin/phpunit --coverage-text

Writing Tests

There are three different unit test directories:

• tests/legacy/unit-tests contains tests for code in the includes directory. No new tests should be added here, ever; existing test classes shouldn't get new tests either. Fixing faulty existing tests is allowed.
• tests/php/includes is where all the new tests for code in the includes directory should be written.
• tests/php/src is where all the tests for code in the src directory should be written.

Each test file should correspond to an associated source file and be named accordingly: * For src code: The base namespace for tests is Automattic\WooCommerce\Tests. A class named Automattic\WooCommerce\TheNamespace\TheClass should have a test named Automattic\WooCommerce\Tests\TheNamespace\TheClassTest. * For includes code: * When testing classes: use the same approach as for src except that namespaces are not used. So a WC_Something class in includes/somefolder/class-wc-something.php should have its tests in tests/src/internal/somefolder/class-wc-something-test.php. * When testing functions: use one test file per functions group file, for example wc-formatting-functions-test.php for code in the wc-formatting-functions.php file.

See also the guidelines for writing unit tests for src code and the guidelines for includes code.

General guidelines for all the unit tests:

• Each test method should cover a single method or function with one or more assertions
• A single method or function can have multiple associated test methods if it's a large or complex method
• Use the test coverage HTML report (under tmp/coverage/index.html) to examine which lines your tests are covering and aim for 100% coverage
• For code that cannot be tested (e.g. they require a certain PHP version), you can exclude them from coverage using a comment: // @codeCoverageIgnoreStart and // @codeCoverageIgnoreEnd. For example, see wc_round_tax_total()
• In addition to covering each line of a method/function, make sure to test common input and edge cases.
• Prefer assertSame() where possible as it tests both type and value
• Remember that only methods prefixed with test will be run so use helper methods liberally to keep test methods small and reduce code duplication. If there is a common helper method used in multiple test files, consider adding it to the WC_Unit_Test_Case class so it can be shared by all test cases
• Filters persist between test cases so be sure to remove them in your test method or in the tearDown() method.
• Use data providers where possible. Be sure that their name is like data_provider_function_to_test (i.e. the data provider for test_is_postcode would be data_provider_test_is_postcode). Read more about data providers here.

Automated Tests

Tests are automatically run with Travis-CI for each commit and pull request.

Code Coverage

Code coverage is available on Codecov which receives updated data after each Travis build.