PluginTestKit (a plugin test development kit)
=============================================

PREMISE

Plugins can and, I think, ought to be just like the main application part of your code. Just like
your application, it ought to be self-sufficient. You should be able to run tests outside of a
specific environment, allowing your plugin to be seen in its proper light. If it doesn't work
in vacuo, it is prone to design flaws because it is relying on the application from which it
came. This is at least the conclusion I came to in writing my own plugins and wanting to develop
them outside the application proper. Plugins by their nature should be usable in other current or
future application with relative ease. Sounds too utopian? Maybe.

INTRODUCTION

It seems rather crazy at first glance, but hopefully this will become a staple among plugin
authors to help them write quick and easy tests for their plugins. The biggest problem with
writing tests for plugins at the moment is that there is no standardised -- in fact, no way --
of just including particular environments relevant to your plugin. You must create custom
requires, hacky includes and configure things manually. It is effectively a short-handed
emulation of boot.rb and environment.rb. In making the most common requirements part of a
standard plugin library, it's my hope to make plugin test writing as simple as it is for
applications.

Before you even consider the small disadvantage of forcing people who use your plugin to install
this one, there is a generator called plugin_test_kit which does all the library and template
copying that you need from the plugin. Whenever you make a new plugin, just call the generator
on it and away you go. To upgrade, just act as if you are installing for the first time -- be
sure to back up any changes you have -- and overwrite the library files and whichever other
files you wish to refresh. The generator can be called both from ./script/generate in a Rails
app or from its own ./generate within the plugin's root directory.

This plugin will of course evolve as my own needs evolve, but if anyone has a particular
assertion, requirement or other feature they would like to see, just ask. Also, any design
changes which you'd like to suggest, I'm all ears. Most of the design I came up with while
writing the README, so it is bound to have flaws.

INSTALLATION

You need to install Plugin Test Kit in your plugins directory. This can be your repository of plugins on which you are working, or the vendor/plugins directory of your Rails application. However, you must use a Rails application to install it first, just like every other plugin. After that point, PTK can start doing its thing.


  $ ./script/plugin source http://mabs29.googlecode.com/svn/trunk/plugins
  $ ./script/plugin install plugin_test_kit

  If you want to move it to a repository of your plugins, outside a Rails app
  $ mv vendor/plugins/plugin_test_kit ../repository/plugins/


Now you can start using it.


USAGE

You have two options for generating the files from the plugin_test_kit library. The first
is using the in-built Rails ./script/generate.

  user:~/ $ cd rails-app
  user:rails-app $ ./rails-app/script/generate plugin wild_chicken
        create  config
        create  fixtures
        create  lib
        create  lib/ptk
        ...
        readme  after_generation

You also have the option of using the generate script provided in plugin_test_kit. It has been
removed of its dependency on a Rails application, allowing you to call it from a repository of
plugins divorced from the root of a Rails application.

  user:~/ $ cd repos/plugins/plugin_test_kit
  user:plugin_test_kit $ ./generate plugin_test_kit plugin_test_kit

AFTERWARDS

Once you have installed the libraries into your own plugin's test directory using the generator,
you will be presented with additional customisations which you can make. The templates contain
further instructions on how to customise each one. You may now treat your test environment pretty
much as you would a normal Rails application test.

Enjoy!