docs/development/testing.md

# Dokku test suite

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.

We maintain the Dokku test harness within the `tests` directory:

- `tests/unit/*.bats`: Bats tests
- `tests/apps/`: Example applications that can be used for tests

## Continuous Integration

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.

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](/dokku/getting-started/install/vagrant)
- Run the following to setup tests and execute them:

  ```shell
  vagrant ssh
  sudo su -
  cd ~/dokku
  make ci-dependencies setup-deploy-tests

  # 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

  # execute all bats tests
  make unit-tests

  # execute all app deployment tests
  make deploy-tests
  ```

Additionally you may run a specific app deployment tests with a target similar to:

```shell
make deploy-test-nodejs-express
```

For a full list of test make targets check out `tests.mk` in the root of the Dokku repository.
[ci skip] document test suite 2015-03-27 14:24:04 -07:00			`# Dokku test suite`

Cleaning testing docs - Simplify test location documentation - Add documentation surrounding our existing CI environment - Dedent items that shouldn't be in a list [ci skip] 2016-07-30 16:51:31 -04:00			`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.`
[ci skip] document test suite 2015-03-27 14:24:04 -07:00
Cleaning testing docs - Simplify test location documentation - Add documentation surrounding our existing CI environment - Dedent items that shouldn't be in a list [ci skip] 2016-07-30 16:51:31 -04:00			We maintain the Dokku test harness within the `tests` directory:
[ci skip] document test suite 2015-03-27 14:24:04 -07:00
Cleaning testing docs - Simplify test location documentation - Add documentation surrounding our existing CI environment - Dedent items that shouldn't be in a list [ci skip] 2016-07-30 16:51:31 -04:00			- `tests/unit/*.bats`: Bats tests
			- `tests/apps/`: Example applications that can be used for tests

			`## Continuous Integration`

			`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.`
[ci skip] document test suite 2015-03-27 14:24:04 -07:00
Cleaning testing docs - Simplify test location documentation - Add documentation surrounding our existing CI environment - Dedent items that shouldn't be in a list [ci skip] 2016-07-30 16:51:31 -04:00			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`
[ci skip] document test suite 2015-03-27 14:24:04 -07:00
Use correct casing for Dokku name lowercase should only be used to refer to the binary, not the project 2016-09-03 04:39:12 -04:00			`- Setup Dokku in a [vagrant vm](/dokku/getting-started/install/vagrant)`
Cleaning testing docs - Simplify test location documentation - Add documentation surrounding our existing CI environment - Dedent items that shouldn't be in a list [ci skip] 2016-07-30 16:51:31 -04:00			`- Run the following to setup tests and execute them:`
[ci skip] document test suite 2015-03-27 14:24:04 -07:00
			```shell
Make testing docs a bit more readable [ci skip] 2016-07-04 20:22:57 -04:00			`vagrant ssh`
			`sudo su -`
			`cd ~/dokku`
			`make ci-dependencies setup-deploy-tests`

			`# execute the entire test suite (linter, bats tests, and app deployment tests)`
			`make test`

Use correct casing for Dokku name lowercase should only be used to refer to the binary, not the project 2016-09-03 04:39:12 -04:00			`# run linter & update vagrant Dokku install from local git clone`
Make testing docs a bit more readable [ci skip] 2016-07-04 20:22:57 -04:00			`make lint copyfiles`

			`# execute all bats tests`
			`make unit-tests`

			`# execute all app deployment tests`
			`make deploy-tests`
[ci skip] document test suite 2015-03-27 14:24:04 -07:00			```

Cleaning testing docs - Simplify test location documentation - Add documentation surrounding our existing CI environment - Dedent items that shouldn't be in a list [ci skip] 2016-07-30 16:51:31 -04:00			`Additionally you may run a specific app deployment tests with a target similar to:`

			```shell
			`make deploy-test-nodejs-express`
			```

Use correct casing for Dokku name lowercase should only be used to refer to the binary, not the project 2016-09-03 04:39:12 -04:00			For a full list of test make targets check out `tests.mk` in the root of the Dokku repository.