Resolves #243: Document how to run a partial set of tests. (#282)

index.md

@@ -10,7 +10,7 @@ Welcome to the BLT documentation site! Please read through the [Quick Start Guid
     * [Running project tasks](readme/project-tasks.md): “how do I _____ on my local machine?”
     * [Best practices](readme/best-practices.md): "how should I write code?"
     * [Workflow](readme/dev-workflow.md): “how do I contribute my code to this project?”
-    * [Automated testing](tests/README.md): “how do I write / run them, and why should I care?”
+    * [Automated testing](readme/testing.md): “how do I write / run them, and why should I care?”
 * Technical Architect
     * [Project Architecture document](readme/architecture.md)
     * [Deploying to cloud](readme/deploy.md)

readme/code-review.md

@@ -61,7 +61,7 @@ It is not possible to create an exhaustive list of all things that should be che
               access and traverse entity properties and fields. Make sure to wrap usages 
               in `try { ... } catch (EntityMetadataWrapperException $e) { ... }`
         * Caution with `hook_init()` and `hook_boot()`
-* __Test coverage__ Does the pull request include required [automated tests](../tests/README.md)? 
+* __Test coverage__ Does the pull request include required [automated tests](readme/testing.md)? 
     * All application functionality should be covered by a functional test via either Behat or PHPUnit
     * All custom libraries should be covered using unit tests via PHPUnit
 * __Documentation__

readme/deploy.md

@@ -21,9 +21,8 @@ Ensure your ACE remote is listed in project.yml under git:remotes.
 ## Creating the build artifact
 
 In order to create the build artifact in `/deploy`, simply run
-```
-blt deploy:build
-```
+
+    blt deploy:build
 
 This task is analogous to `setup:build` but with a few critical differences:
 
@@ -38,45 +37,26 @@ After the artifact is created, you can inspect it or even run it as a website lo
 
 To both create and deploy the build artifact in a single command, run the following command
 
-````
-blt deploy -Ddeploy.branch=develop-build -Ddeploy.commitMsg='BLT-123: The commit message.'
-````
+    blt deploy -Ddeploy.branch=develop-build -Ddeploy.commitMsg='BLT-123: The commit message.'
 
 This command will commit the artifact to the `develop-build` branch with the specified commit message and push it to the remotes defined in project.yml.
 
 ## Modifying the artifact
 
-The artifact is built by:
+The artifact is built by running the `deploy:build` target, which does the following:
 
 * Rsyncing files from the repository root
 * Re-building dependencies directly in the deploy directory. E.g., `composer install`
 
-You can modify the build artifact in a few ways:
-
-1. Change which files are rsynced to the artifact by providing your own `deploy.exclude_file` value in project.yml. See [upstream deploy-exclude.txt](https://github.com/acquia/blt/blob/8.x/phing/files/deploy-exclude.txt) for example contents.  E.g.,
-
-          deploy:
-            exclude_file: ${repo.root}/blt/deploy/rsync-exclude.txt
-
-1. Change which files are gitignored in the artifact by providing your own `deploy.gitignore_file` value in project.yml. See [upstream .gitignore](https://github.com/acquia/blt/blob/8.x/phing/files/.gitignore) for example contents. E.g.,
-
-          deploy:
-            gitignore_file: ${repo.root}/blt/deploy/.gitignore
-
-1. Execute a custom command after the artifact by providing your own `target-hooks.post-deploy-build.dir` and `target-hooks.post-deploy-build.command` values in project.yml. E.g.,
+The rsync and re-build processes can be configured using the `deploy` Phing variable.
 
-          # Executed after deployment artifact is created.
-          post-deploy-build:
-            dir: ${deploy.dir}/docroot/profiles/contrib/lightning
-            command: npm run install-libraries
+See [Extending BLT](extending-blt.md) for more information on overriding Phing variables.
 
 ### Debugging deployment artifacts
 
 If you would like to create, commit, but _not push_ the artifact, you may do a dry run:
 
-````
-blt deploy -Ddeploy.branch=develop-build -Ddeploy.commitMsg='BLT-123: The commit message.' -Ddeploy.dryRun=true
-````
+    blt deploy -Ddeploy.branch=develop-build -Ddeploy.commitMsg='BLT-123: The commit message.' -Ddeploy.dryRun=true
 
 This is helpful for debugging deployment artifacts.
 

readme/extending-blt.md

@@ -37,3 +37,78 @@ You can override the value of any Phing variable used by BLT by either:
         blt tests:behat -propertyfile mycustomfile.yml -propertyfileoverride
 
 
+## Modifying BLT Configuration
+
+BLT configuration can be customized by overriding the value of default variable values. You can find the default value of any BLT variable in [build.yml](https://github.com/acquia/blt/blob/8.x/phing/build.yml).
+
+Listed below are some of the more commonly customized BLT targets.
+
+### deploy:*
+
+#### deploy:build
+
+To modify the behavior of the `deploy:build` target, you may override BLT's `deploy` configuration:
+
+       deploy:
+         build-dependencies: true
+         dir: ${repo.root}/deploy
+         exclude_file: ${blt.root}/phing/files/deploy-exclude.txt
+         gitignore_file: ${blt.root}/phing/files/.gitignore
+
+More specifically, you can modify the build artifact in the following key ways:
+
+1. Change which files are rsynced to the artifact by providing your own `deploy.exclude_file` value in project.yml. See [upstream deploy-exclude.txt](https://github.com/acquia/blt/blob/8.x/phing/files/deploy-exclude.txt) for example contents.  E.g.,
+
+          deploy:
+            exclude_file: ${repo.root}/blt/deploy/rsync-exclude.txt
+
+1. Change which files are gitignored in the artifact by providing your own `deploy.gitignore_file` value in project.yml. See [upstream .gitignore](https://github.com/acquia/blt/blob/8.x/phing/files/.gitignore) for example contents. E.g.,
+
+          deploy:
+            gitignore_file: ${repo.root}/blt/deploy/.gitignore
+
+1. Execute a custom command after the artifact by providing your own `target-hooks.post-deploy-build.dir` and `target-hooks.post-deploy-build.command` values in project.yml. E.g.,
+
+          # Executed after deployment artifact is created.
+          post-deploy-build:
+            dir: ${deploy.dir}/docroot/profiles/contrib/lightning
+            command: npm run install-libraries
+
+### tests:*
+
+#### tests:behat
+
+To modify the behavior of the tests:behat target, you may override BLT's `behat` configuration:
+
+        behat:
+          config: ${repo.root}/tests/behat/local.yml
+          profile: local
+          # If true, `drush runserver` will be used for executing tests.
+          run-server: false
+          # This is used for ad-hoc creation of a server via `drush runserver`.
+          server-url: http://127.0.0.1:8888
+          # If true, PhantomJS GhostDriver will be launched with Behat.
+          launch-phantom: true
+          # An array of paths with behat tests that should be executed.
+          paths:
+            - ${docroot}/modules
+            - ${docroot}/profiles
+            - ${repo.root}/tests/behat
+          tags: '~ajax'
+
+
+### validate:*
+
+#### validate:phpcs
+
+To modify the behavior of the validate:phpcs target, you may override BLT's `phpcs` configuration:
+
+        phpcs:
+          filesets:
+            - files.php.custom.modules
+            - files.php.tests
+            - files.frontend.custom.themes
+
+The phpcs.filesets array contains references to Phing `<fileset>`s. You can remove or add your own custom filesets to the phpcs.filesets array. 
+
+The default filesets are defined in [filesets.xml](https://github.com/acquia/blt/blob/8.x/phing/tasks/filesets.xml).

readme/onboarding.md

@@ -94,4 +94,4 @@ Review review the following documentation:
 * [Repository architecture](repo-architecture.md): “how is the code organized, and why?”
 * [Running project tasks](project-tasks.md): “how do I _____ on my local machine?”
 * [Workflow](dev-workflow.md): “I wrote code, how does it get from here to there?”
-* [Automated testing](../tests/README.md): “how do I write / run them, and why should care?”
+* [Automated testing](readme/testing.md): “how do I write / run them, and why should care?”

readme/project-tasks.md

@@ -22,43 +22,36 @@ Please see [Deploy](deploy.md) for a detailed description of how to deploy to Ac
 
 ## Run tests & code validation
 
-Please see [tests/README.md](../tests/README.md) for information on running tests.
+Please see [readme/testing.md](readme/testing.md) for information on running tests.
 
 To execute PHP codesniffer and PHP lint against the project codebase, run:
 
-```
-blt validate:all
-```
+    blt validate:all
 
 ## Build front end assets
 
 Ideally, you will be using a theme that uses SASS/SCSS, a styleguide, and other tools that require compilation. Like dependencies, the compiled assets should not be directly committed to the project repository. Instead, they should be built during the creation of a production-ready build artifact.
 
 BLT allows you to define a custom command that will be run to compile your project's frontend assets. You can specify the command in your project's `project.yml` file under the `target-hooks.frontend-build` key:
 
-```
-target-hooks:
-  frontend-build:
-    # The directory in which the command will be executed.
-    dir: ${docroot}
-    command: npm install.
-```
+
+    target-hooks:
+      frontend-build:
+        # The directory in which the command will be executed.
+        dir: ${docroot}
+        command: npm install.
 
 If you need to run more than one command, you may use this feature to call a custom script:
 
-```
-target-hooks:
-  frontend-build:
-    # The directory in which the command will be executed.
-    dir: ${repo.root}
-    command: ./scripts/custom/my-script.sh
-```
+    target-hooks:
+      frontend-build:
+        # The directory in which the command will be executed.
+        dir: ${repo.root}
+        command: ./scripts/custom/my-script.sh
 
 This command will be executed when dependencies are built in a local or CI environment, and when a deployment artifact is generated. You may execute the command directly by calling the `frontend:build` target:
 
-```
-blt frontend:build
-```
+    blt frontend:build
 
 ## Updating your local environment
 
@@ -68,20 +61,14 @@ The project is configured to update the local environment with a local drush ali
 
 This all in one command will make sure your local is in sync with the remote site.
 
-```
-blt local:refresh
-```
+    blt local:refresh
 
 ### Sync: Copy the database from the remote site
 
-```
-blt local:sync
-```
+    blt local:sync
 
 ### Update: Run update tasks locally
 
-```
-blt local:update
-```
+    blt local:update
 
 These tasks can be seen in `build/core/phing/tasks/local-sync.xml`. An additional script can be added at `/hooks/dev/post-db-copy/dev-mode.sh` which would run at the end of this task.