kitkat

88      a8P   88  888888888888  88      a8P          db    888888888888  
88    ,88'    88       88       88    ,88'          d88b        88       
88  ,88"      88       88       88  ,88"           d8'`8b       88       
88,d88'       88       88       88,d88'           d8'  `8b      88       
8888"88,      88       88       8888"88,         d8YaaaaY8b     88       
88P   Y8b     88       88       88P   Y8b       d8""""""""8b    88       
88     "88,   88       88       88     "88,    d8'        `8b   88       
88       Y8b  88       88       88       Y8b  d8'          `8b  88

###################################################################################

Kontinuos Integrated Testing Koffee Application Template

Introduction

Kitkat is an application testing framework for projects that we are working on in Postmedia, the basis for this project was to create something that would automate the testing of our coffee-script files and should require as little configuration or interaction as possible. "Convention over Configuration"

It's primarily meant to serve internal purposes as Postmedia Network Inc, however it is being open sourced under the MIT License. Others may find some use for what we are doing, and still others may be able to help turn this into a more generic and useful solution by contributing and/or correcting our ignorant ways.

Be kind. We're coming from years of .NET experience and some Ruby on Rails. This is our first foray into Node.js development and we're still figuring things out. Constructive criticism is encouraged. If you see something odd and think to yourself "WTF?" then by all means, let us know. We are eager and willing to learn.

Installing

You can install this in one of two methods, locally to your project:

mkdir someProject
cd someProject
npm install kitkat

Alternatively this may be installed globally assuming your npm prefix for global installs points to /usr/local (See troubleshooting below)

npm install -g kitkat

Once kitkat is installed you need only be in the project folder to execute the command as per the usage section, if you are not going to use the src/ path in your project for your source coffee files or spec/ for spec.coffee files then please copy and modify the example kitkat_config.js in this packages (kitkat) folder, place the file into the root folder of your project.

Also if you installed locally be aware you can not find kitkat in your Path, therefore run kitkat from your project directory with './node_modules/kitkat/bin/kitkat'

Using

To generate a spec file for a single coffee source file

kitkat --spec [/path/to/somefile.coffee]

To generate spec files for an entire path that contains coffee script files, this is recursive based on path given, if no path is given it is assumed to use current directory.

kitkat --spec

To start kitkat's automated testing and build mechanism you can do one of the following:

detect and test automatically

kitkat

detect, test, autospec files not spec'd

kitkat --autospec

If you just need to run a static quick test over all current specs

kitkat --test

Customize with kitkat.config.js

If you have a project with special needs, aka a src or destination directory that is not following our convention or there is no need to compile the source files being monitored then this is the file you need in your projects root directory. Copy the file from kitkat's installed location and then modify it to match the settings you require, a listing of the settings is below:

noCompile - Will not compile the coffee files in your prodSrcDir during testing.  
safetyOff - Will not verify the directories used are present nor autogenerate the app.coffee and app.spec.coffee files
prodSrcDir - folder location for .coffee files being monitored (default is src/)
specFileDir - folder location for .spec.coffee files to be executed during tests (default is spec/)
prodDeployDir - folder to contain complied .coffee files (default is lib/)

Example steps to create a new application using kitkat

1. Create and change directory into the folder where your project will reside

   $ mkdir myapp $ cd myapp

2. Run kitkat, by default it will create the required folders and a default app.coffee file

   $ kitkat [Fri, 09 Sep 2011 11:57:38 GMT] NOTICE Kitkat - Kontinuous Integrated Testing Koffee Application Template [Fri, 09 Sep 2011 11:57:38 GMT] NOTICE press CTRL-C to quit

   [Fri, 09 Sep 2011 11:57:38 GMT] WARNING The spec path was not found, this has been created. [Fri, 09 Sep 2011 11:57:38 GMT] WARNING The src path was not found, this has been created and a default app.coffee file created. [Fri, 09 Sep 2011 11:57:38 GMT] NOTICE Monitoring and testing current project [Fri, 09 Sep 2011 11:57:38 GMT] NOTICE Watch added for /path/to/your/app/myapp/src/app.coffee

By convention we use the following folders in every project, kitkat expects that these exist or it will create them.

• Deployment: lib/ (Only if the noCompile configuration is false, default is true)
• Spec Files: spec/
• Coffee Files: src/

1. Start coding.

By default you have your folder structure and an empty app.coffee to work with, you will need to create a spec file for testing which uses the file naming convention of app.spec.coffee where the file name is identical to your source file but inserts '.spec' into the file name.

Considerations for running kitkat

Start kitkat monitoring and testing

$ kitkat

or

$ kitkat —autospec

The difference above only determines if kitkat will generate new (autospec) spec files when you add new .coffee files into the src/ path, otherwise the output will be essentially the same indicating that it has added watches for the initial app.coffee file and created any paths that were missing.

Testing will only if you had an existing spec file or after you have changed the code file or spec file (as there is nothing to test if kitkat created them), all initial tests created by autospec will fail because you have not created any and any tests run with no spec files present will fail because you have no test modules.

Acknowledgments

Parts of this are very much a result of other projects, as such credit is due to varios people for blazing the way and providing me with enough understanding to take what they had and build what kitkat is now, these include:

Miško Hevery - https://github.com/mhevery/jasmine-node
TJ Holowaychuk - https://github.com/visionmedia/expresso
Trevor Menagh - https://github.com/trevmex/EnvJasmine

Whether you knew it or not, your projects were either depended on or used heavily in the early parts of kitkat.

Third party modules

• optimist - provides a very light weight command line argument processor
• async - some advanced flow control for node.js applications
• growl - notification system (requires growlnotify extra in order to work)
• stalker - recursive directory monitoring for file changes
• coloured-log - great colourized log output
• coffee-script - the core of this project is written in and supports coffee-script

Outstanding issues

• None that I can identify (yet) but please let us know if you find any.

Troubleshooting

Global Installations To install using the global prefix, be sure that you have ownership to /usr/local/ and that your npm configuration has the global install prefix set to /usr/local as per the following steps:

Changing ownership of /usr/local

sudo chown -R $USER /usr/local

Check npm global prefix

npm config get prefix

If it is not pointed to /usr/local then you can change it by issuing the following

npm config set prefix=/usr/local

Be cautious about this change, this is a controversial setting and discussion, it makes it easy to run the application, alternatives can include making a symlink of the kitkat folder to the /usr/local location or adding the bin folder within kitkat inside your project to your path statement such that the program is found when you issue the kitkat command.

Created by

• Keith Benedict
• Edward de Groot
• Stephen Veerman
• Kevin Gamble