Issue #2833290 by navneet0693, Mile23, eojthebrave, Torenware: TESTING.md does not explain how to test the modules

Author: navneet0693

STANDARDS.md

@@ -6,18 +6,18 @@ Examples uses mostly the same coding standards as Drupal core.
 If you see a discrepancy between the coding standards tools used by core and
 those used by Examples, please file an issue so that Examples can follow core.
 
-Examples uses the phpcs tool to allow for checking PHP coding standards. We also
-use eslint for JavaScript coding standards.
+Examples uses the `phpcs` tool to allow for checking PHP coding standards. We
+use the `drupal/coder` project for Drupal-specific coding standards.
 
-Examples has a `phpcs.xml.dist` file at the root of the project. This file
-specifies the current coding standards 'sniffs' which code in the project must
-pass.
+We also use `eslint` for JavaScript coding standards.
 
-The `phpcs.xml.dist` file is used by a tool called PHP_CodeSniffer (`phpcs`).
+Examples has a `phpcs.xml.dist` file at the root of the project. phpcs uses this
+file to specify the current coding standards 'sniffs' which code in the project
+must pass.
 
 Contributors should install `phpcs` in their local Drupal installation, and then
 use that to run `phpcs` against Examples as part of their development and review
-process.
+process. (See details below on how to install and run this tool.)
 
 Contributors can also patch the `phpcs.xml.dist` file itself, in order to fix
 the codebase to pass a given rule or sniff. Patches which do this should be
@@ -47,6 +47,10 @@ Like this:
     $ ../vendor/bin/phpcs -e --standard=Drupal
     // Shows you a bunch of Drupal-related sniffs.
 
+Note that there is an issue to require Coder and phpcs as part of Drupal core:
+https://www.drupal.org/node/2744463 Once this issue is fixed, you shouldn't need
+to install phpcs before using it.
+
 Running phpcs
 -------------
 

TESTING.md

@@ -15,6 +15,12 @@ the testbot's behavior.
 You can find information on how to run `run-tests.sh` locally here:
 https://www.drupal.org/node/645286
 
+Examples is always targeted to the dev branch of Drupal core for the latest
+release. As of this writing, the latest release of Drupal core is 8.2.5, which
+means development for Examples should be against the Drupal 8.2.x development
+branch. When Drupal 8.3.0 is released, we'll start targeting Examples to 8.3.x,
+and so on.
+
 You should at least run `run-tests.sh` locally against all the changes in your
 patch before uploading it.
 
@@ -27,8 +33,68 @@ suggested workaround for this, since there is no best practice to demonstrate as
 an example. There is, however, this issue in core:
 https://www.drupal.org/node/2499239
 
+How To Run The Tests In The Drupal UI
+-------------------------------------
+
+Generally, you should run tests from the command line. This is generally easier
+than using Drupal's testing UI. However, here's how you can do it that way:
+
+Enable the Testing module.
+
+Visit the test list page at `admin/config/development/testing`.
+
+Since the tests are organized by module, you can search for a module name and
+get all the tests for that module. For instance, type in 'node_type_example' for
+all the tests related to that module.
+
+Click the check boxes next to the tests you want to run. If you find this
+tedious, it's time to learn to use the command line. :-)
+
+Click 'Run Tests.' You're now running the tests.
+
+Step-by-step: How To Run The Tests.
+-----------------------------------
+
+Begin with an installed Drupal codebase. Make a codebase, set up the database,
+etc. Note that you can use an existing Drupal instance but the best practice is
+to start fresh. Something not working right? Try a new installation.
+
+Use the dev branch of core for the latest release of Drupal. As of this writing,
+it's 8.2.x. When Drupal 8.3.0 is released, we'll target 8.3.x.
+
+Open the terminal window and move to the root directory of the Drupal
+installation:
+
+	$ cd path/to/drupal
+
+Put Examples into the `modules/` folder of the Drupal installation. If you are
+doing development on Examples, you should have already checked out the git
+repository into `modules/`, like this:
+
+	$ git clone --branch 8.x-1.x https://git.drupal.org/project/examples.git modules/examples
+
+Now you can run `run-tests.sh`, which, despite having a `.sh` suffix is not a
+shell script. It's a PHP script.
+
+You'll use the `--directory` option to have the test runner scan the Examples
+module directory for tests.
+
+Also, importantly, if your test site has its own URL, you'll need to supply that
+with the `--url` option. For instance, under MAMP, you must specify
+`--url http://localhost:8888/`.
+
+You can also use `--concurrency` to speed up the test run, and `--browser` to
+see detailed test results in a web browser instead of just text output in the
+terminal.
+
+	$ php ./core/scripts/run-tests.sh --browser --concurrency 10 --url http://localhost:8888/ --directory modules/examples
+
+This should run all the tests present in Examples. If you add a test and it
+doesn't appear in the list of tests to run, then you'll need to double-check
+that it's in the proper test namespace and that the class name (and thus the
+file name) ends in Test.
 
-What Tests Should An Example Project Have?
+What Tests Should An Example Module Have?
 ------------------------------------------
 
 Examples has a checklist for each module: