From a09cda126b9be58127d66e0dfd8570b2fccb62c8 Mon Sep 17 00:00:00 2001 From: Tan Jay Jun Date: Fri, 12 Jul 2019 15:47:55 +0800 Subject: [PATCH] docs: improve testing docs --- docs/development/testing.md | 29 ++++++++++++++++++----------- 1 file changed, 18 insertions(+), 11 deletions(-) diff --git a/docs/development/testing.md b/docs/development/testing.md index 90ea77a1a..124c922ff 100644 --- a/docs/development/testing.md +++ b/docs/development/testing.md @@ -1,6 +1,6 @@ -# Dokku test suite +# Running Tests -Dokku has a full test suite to assist in quick iterating development. These tests include a linter using [shellcheck](https://github.com/koalaman/shellcheck), functional unit tests using the [bats testing framework](https://github.com/sstephenson/bats), and a deployment suite of example apps that use the most popular languages and frameworks. +Dokku has a full test suite to assist in quick iterating development. These tests include a linter using [shellcheck](https://github.com/koalaman/shellcheck), functional unit tests using the [Bats testing framework](https://github.com/bats-core/bats-core), and a deployment suite of example apps that use the most popular languages and frameworks. We maintain the Dokku test harness within the `tests` directory: @@ -11,13 +11,13 @@ We maintain the Dokku test harness within the `tests` directory: All pull requests have tests run against them on [CircleCI](https://circleci.com/), a continuous integration platform that provides Docker support for Ubuntu Trusty 14.04. -If you wish to skip tests for a particular commit - e.g. Documentation changes - you may add the `[ci skip]` designator to your commit message. Commits that *should* be tested but have the above designator will not be merged. +If you wish to skip tests for a particular commit, e.g. documentation changes, you may add the `[ci skip]` designator to your commit message. Commits that _should_ be tested but have the above designator will not be merged. While we do provide official packages for a variety of platforms, as our test suite currently runs on Ubuntu Trusty 14.04, we only provide official installation support for that platform. ## Local Test Execution -- Setup Dokku in a [vagrant vm](/docs/getting-started/install/vagrant.md) +- Setup Dokku in a [Vagrant VM](/docs/getting-started/install/vagrant.md). - Run the following to setup tests and execute them: ```shell @@ -29,11 +29,8 @@ While we do provide official packages for a variety of platforms, as our test su # execute the entire test suite (linter, bats tests, and app deployment tests) make test - # run linter & update vagrant Dokku install from local git clone - make lint copyfiles - - # build a specific plugin - make go-build-plugin copyplugin PLUGIN_NAME=apps + # run linter + make lint # execute all bats tests make unit-tests @@ -42,6 +39,16 @@ While we do provide official packages for a variety of platforms, as our test su make deploy-tests ``` +After making changes to your local Dokku clone, don't forget to update the Vagrant Dokku install. + +```shell +# update vagrant dokku install from local git clone +make copyfiles + +# build a specific plugin +make go-build-plugin copyplugin PLUGIN_NAME=apps +``` + Additionally you may run a specific app deployment tests with a target similar to: ```shell @@ -66,7 +73,7 @@ bats tests/unit/10_apps.bats tests/unit/10_certs.bats ## Executing a single test -In order to increase testing velocity, a wrapper script around bats is available that can be used to run a single testcase within a suite. +In order to increase testing velocity, a wrapper script around Bats is available that can be used to run a single test case within a suite. Tests within a suite may be listed by specifying the suite as a parameter to the `tests/bats-exec-test-single` script. @@ -80,7 +87,7 @@ A single test can be specified as a second parameter. The test is selected by fu tests/bats-exec-test-single tests/unit/10_apps.bats clone ``` -Some special characters are translated in the test listing - specifically the characters `( ) :` - while others are not. The fuzzy matching happens on the test names listed when no second character is invoked, so executing a test with a more specific name will work as expected. +Some special characters are translated in the test listing, specifically the characters `( ) :`, while others are not. The fuzzy matching happens on test names as listed by this script, so executing a test with a more specific name will work as expected. ```shell tests/bats-exec-test-single tests/unit/10_apps.bats clone_-2d-2dskip-2ddeploy