From e8abe496e8ef9842e97677c1e6c18cb344ce039c Mon Sep 17 00:00:00 2001 From: Andrew Coulton Date: Thu, 17 Jul 2014 22:58:40 +0100 Subject: [PATCH] Update and clarify README --- README.md | 147 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 98 insertions(+), 49 deletions(-) diff --git a/README.md b/README.md index 0d5541b..3949b38 100644 --- a/README.md +++ b/README.md @@ -1,76 +1,71 @@ -koharness - create clean Kohana containers for testing your modules +koharness - bootstrap a clean Kohana app for testing your modules =================================================================== -koharness is a very simple package to help you provide a clean testing environment for your Kohana -modules. Once enabled, it will generate a basic Kohana application containing your module and any -dependencies, which you can then use as the basis for running tests with your favourite tools. +koharness is a very simple package (read, hack) that provides a clean testing environment for +your Kohana modules. It can generate a basic Kohana application containing your module and +any dependencies, which you can then use to run tests with your favourite tools. -Unlike the standard Kohana test bootstrappers, koharness allows you to control module loading order, -which may be vital for modules that are designed to extend other modules. +koharness gives you full control of module loading order, which may be vital for modules +that are designed to extend others using the Cascading File System. -## Adding it as a project dependency +## Installing koharness in your module -The easiest way to add koharness to your project is with [composer](http://getcomposer.org). Create -a composer.json in the root of your module's folder like so: +Add it as a development dependency in your module's composer.json: ```json { "require-dev": { - "ingenerator/koharness" : "*" + "kohana/koharness" : "*@dev" } } ``` -Ensure your .gitignore file includes the following lines: +Run `composer install` in your module's root directory. -``` -/vendor -/modules -``` +## Configuring module dependencies -Run `composer install --dev` in your module's root directory. +Your module will almost certainly require the kohana core (if it doesn't you can probably +test it in isolation without koharness or any other bootstrapper - which is obviously good). -## Configuring module dependencies +If you want to use phpunit, you'll probably also want the Kohana unittest module. -Your module will require at least the Kohana core and the Kohana unittest module to function - and -it may require other modules too. We recommend tracking these dependencies in your composer.json too -- currently the core Kohana repository doesn't define composer packages so you should use the -inGenerator forks: +Add them (and anything else you need) to your composer.json too. For extra cleanliness, +force composer-installers to install kohana modules into the normal vendor path instead +of into /modules (note, this won't affect end-users of your module). ```json { "require": { - "kohana/core": "dev-ingenerator-master", - "kohana/unittest": "dev-ingenerator-master" + "kohana/core": "3.3.*", }, - "repositories": [ - {"type": "vcs", "url": "https://github.com/ingenerator/kohana-core"}, - {"type": "vcs", "url": "https://github.com/ingenerator/kohana-unittest"} - ] + "require-dev": { + "kohana/unittest": "3.3.*", + "kohana/koharness" : "*@dev" + }, + "extra": { + "installer-paths": { + "vendor/{$vendor}/{$name}": ["type:kohana-module"] + } + } } ``` -Alternatively, you could define custom packages in your module's composer.json that track the -specific git revision in the main Kohana repositories. +This will get all the dependencies installed on your machine, but you need to tell koharness how +to bootstrap them for your test environment and the order that they should be loaded by +Kohana::modules(). -Or, add a shell script to your project to clone the required repositories and checkouts to your -local disk. - -However you get your dependencies to your machine, you then need to configure koharness to include -them in your Kohana installation's active module list. You do this with a koharness.php file in the -repository root: +Add a `koharness.php` file in the repository root: ```php // {my-module-root}/koharness.php return array( + // This list of paths will also be passed to Kohana::modules(). Define the modules (including your own) + // in the order you want them to appear in Kohana::modules() 'modules' => array( 'my-module' => __DIR__, - 'unittest' => __DIR__.'/modules/unittest' // Or any other way you want to specify the path to this module + 'unittest' => __DIR__.'/vendor/kohana/unittest' ), - // You can specify where to look for Kohana core - the default is {my-module-root}/vendor/kohana/core - 'syspath' => '/some/path/to/kohana/core', - // You can specify where to create the harness application - the default is /tmp/koharness 'temp_dir' => '/home/me/testing' ); @@ -78,26 +73,80 @@ return array( ## Building your harness -To build your harness, from your module root directory just run `vendor/bin/koharness` (presuming -you have left your composer `bin-dir` property at default. This will: +Now you have your module in a directory with all its dependencies inside it - so it needs to be +turned "inside out" to be more like a standard app with your module as a dependency. Here's where +koharness does it's thing. -* Wipe out your specified temp directory -* Create a standard generic Kohana directory structure in the temp directory -* Link the kohana core directory to {temp}/system -* Link each module to {temp}/modules/{name} -* Link your module's vendor path to {temp}/vendor -* Customise the generic application bootstrap with your module list and output it to {temp}/application/bootstrap.php +In your module root directory, just run `vendor/bin/koharness` (presuming you're using composer's default +`bin-dir` setting). This will **wipe out your specified temp_dir** and build a structure of symlinks and +files that looks like this: + +``` +$temp_dir +\---application +| \---cache +| \---logs +| | bootstrap.php +| +\---modules +| \---my-module -> WORKING_DIR +| \---unittest -> WORKING_DIR/vendor/kohana/unittest +| +\---system -> WORKING_DIR/vendor/kohana/core +\---vendor -> WORKING_DIR/vendor +``` + +The bootstrap.php is generated from a standard Kohana 3.3 template that ships with koharness, with your +modules included. ## Running tests -Once you have built your harness, you can run tests using whatever tool you prefer. For example, you -could use phpunit: +Once you have built your harness, you can run tests using whatever tool you prefer. + +### PHPUnit with the kohana unittest module + +Easy peasy: ```shell cd /tmp/koharness vendor/bin/phpunit --bootstrap=modules/unittest/bootstrap.php modules/unittest/tests.php ``` +### Other tools + +If you want to load your kohana environment in phpspec, behat or similar then you'll also +find your module working directory contains a `koharness_bootstrap.php` that defines the +various path constants that you'd normally get from index.php or the unittest module runner. + +In phpspec for example, you could just do something like this: + +```php +// MODULE_ROOT/spec/ObjectBehavior.php +