<commit_before>Buildpack Testrunner
=====================

A simple unit testing framework for testing buildpacks based on
[shUnit2](http://code.google.com/p/shunit2/). It provides utilities for
loading buildpacks and capturing and asserting their behavior. It can be run
locally, as part of a continuous integration system, or even directly on Heroku
as a buildpack itself. To run the testrunner locally, see the Setup and Usage
sections below. To run on Heroku, see the Running Buildpack Tests on Heroku section.

Setup
-----

To use the testrunner locally, first clone this repository:

    git clone https://github.com/heroku/heroku-buildpack-testrunner

If you do not already have shUnit2 installed, either
[download](http://code.google.com/p/shunit2/downloads/list) it or checkout it
out from SVN:

    svn checkout http://shunit2.googlecode.com/svn/trunk/ shunit2

Do not use `apt-get` for obtaining shUnit2 because it is the wrong version.

Once you have shUnit2, set an `SHUNIT_HOME` environment variable to the root
of the version you wish to use. For example:

    export SHUNIT_HOME=/usr/local/bin/shunit/source/2.1

Usage
-----

To run the tests for one or more buildpacks, execute:

    bin/run [-c] [-s single_suite_test.sh] buildpack_1 [buildpack_2 [...]]

where `buildpack_n` can either be a local directory or a remote Git repository
ending in `.git`. Each buildpack must have a `test` directory and files
matching the `*_test.sh` pattern to be run. The `-s` flag sets a single test
suite to run in the `test` directories of the buildpacks. The `-c` flag
enables persistent caching of files downloaded with cUrl. See
`lib/magic_curl/README.md` for more info.

For example, the following command:

    bin/run ~/a_local_buildpack git@github.<EMAIL>:heroku/heroku-buildpack-gradle.git

Would first run the tests in the buildpack at `~/a_local_buildpack` and then
clone the Git repository at `<EMAIL>:rbrainard/heroku-buildpack-
gradle.git` into a temp directory and run the tests there too.

Running Buildpack Tests on Heroku
---------------------------------

The testrunner is itself a buildpack and can be used to run tests for your
buildpack on Heroku. This can be very helpful for testing your buildpack on a
real Heroku dyno before pushing it to a public repo. To do this, create a
Cedar app out of your buildpack and set the testrunner as its buildpack:

    $ cd your_buildpack_dir
    $ heroku create --stack cedar --buildpack git://github.com/heroku/heroku-buildpack-testrunner.git

    Creating deep-thought-1234... done, stack is cedar
    http://deep-thought-1234.herokuapp.com/ | <EMAIL>:deep-thought-1234.git
    Git remote heroku added

Once the testrunner is set as your buildpack's buildpack, push it to Heroku.
This will automatically download and install shUnit2 and create a `tests`
process for you:

    $ git push heroku master

    Counting objects: 425, done.
    Delta compression using up to 8 threads.
    Compressing objects: 100% (271/271), done.
    Writing objects: 100% (425/425), 48.08 KiB, done.
    Total 425 (delta 126), reused 396 (delta 113)

    -----> Heroku receiving push
    -----> Fetching custom buildpack... done
    -----> Buildpack Test app detected
    -----> Downloading shunit2-2.1.6..... done
    -----> Installing shunit2-2.1.6.... done<commit_msg>cedar is default<commit_after>Buildpack Testrunner
=====================

A simple unit testing framework for testing buildpacks based on
[shUnit2](http://code.google.com/p/shunit2/). It provides utilities for
loading buildpacks and capturing and asserting their behavior. It can be run
locally, as part of a continuous integration system, or even directly on Heroku
as a buildpack itself. To run the testrunner locally, see the Setup and Usage
sections below. To run on Heroku, see the Running Buildpack Tests on Heroku section.

Setup
-----

To use the testrunner locally, first clone this repository:

    git clone https://github.com/heroku/heroku-buildpack-testrunner

If you do not already have shUnit2 installed, either
[download](http://code.google.com/p/shunit2/downloads/list) it or checkout it
out from SVN:

    svn checkout http://shunit2.googlecode.com/svn/trunk/ shunit2

Do not use `apt-get` for obtaining shUnit2 because it is the wrong version.

Once you have shUnit2, set an `SHUNIT_HOME` environment variable to the root
of the version you wish to use. For example:

    export SHUNIT_HOME=/usr/local/bin/shunit/source/2.1

Usage
-----

To run the tests for one or more buildpacks, execute:

    bin/run [-c] [-s single_suite_test.sh] buildpack_1 [buildpack_2 [...]]

where `buildpack_n` can either be a local directory or a remote Git repository
ending in `.git`. Each buildpack must have a `test` directory and files
matching the `*_test.sh` pattern to be run. The `-s` flag sets a single test
suite to run in the `test` directories of the buildpacks. The `-c` flag
enables persistent caching of files downloaded with cUrl. See
`lib/magic_curl/README.md` for more info.

For example, the following command:

    bin/run ~/a_local_buildpack git@github.<EMAIL>:heroku/heroku-buildpack-gradle.git

Would first run the tests in the buildpack at `~/a_local_buildpack` and then
clone the Git repository at `<EMAIL>:rbrainard/heroku-buildpack-
gradle.git` into a temp directory and run the tests there too.

Running Buildpack Tests on Heroku
---------------------------------

The testrunner is itself a buildpack and can be used to run tests for your
buildpack on Heroku. This can be very helpful for testing your buildpack on a
real Heroku dyno before pushing it to a public repo. To do this, create a
Cedar app out of your buildpack and set the testrunner as its buildpack:

    $ cd your_buildpack_dir
    $ heroku create --buildpack git://github.com/heroku/heroku-buildpack-testrunner.git

    Creating deep-thought-1234... done, stack is cedar
    http://deep-thought-1234.herokuapp.com/ | <EMAIL>:deep-thought-1234.git
    Git remote heroku added

Once the testrunner is set as your buildpack's buildpack, push it to Heroku.
This will automatically download and install shUnit2 and create a `tests`
process for you:

    $ git push heroku master

    Counting objects: 425, done.
    Delta compression using up to 8 threads.
    Compressing objects: 100% (271/271), done.
    Writing objects: 100% (425/425), 48.08 KiB, done.
    Total 425 (delta 126), reused 396 (delta 113)

    -----> Heroku receiving push
    -----> Fetching custom buildpack... done
    -----> Buildpack Test app detected
    -----> Downloading shunit2-2.1.6..... done
    -----> Installing shunit2-2.1.6.... done
{'fraction_non_alphanumeric': 0.09992452830188679, 'fraction_numerical': 0.021433962264150945, 'mean_word_length': 3.480054090601758, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 19, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 10, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '845284', 'n_tokens_mistral': 2055, 'n_tokens_neox': 1897, 'n_words': 839}