kitkat-express

kitkat - express

Kontinuos Integrated Testing Koffee Application Template - setup for the express/expresso testing on the simplified branch, all mention in this readme to kitkat refers to kitkat-express.

Introduction

Kitkat is a first attempt to create 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"

Parts of this are very much a result of other projects and ddepend on those for the various pieces to work, https://github.com/trevmex/EnvJasmine and other assistance from Trevor Menagh amongst others has helped this get to an alpha stage with much more work to do.

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-express

Once kitkat is installed you need only be in the project folder to execute the command as per the usage section.

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

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

Kitkat assumes you have the following folder structure, or it will create it:

• Deployment: lib/
• Spec Coffee Files: spec/
• Coffee Files: src/

1. Initialize the folders by running kitkat —spec

   $ kitkat —spec 26 Jul 10:59:58 – Generating spec files…… 26 Jul 10:59:58 – Error: ENOENT, No such file or directory ‘/path/to/your/app/src/.coffee’

Disregard the error if it appears, this is expected as you are initializing the project and no source files exist yet, verify the folders are now present.

$ ls
dependency lib mocks source spec

1. Create a blank coffee file for your application and generate the default spec

   $ touch src/main.coffee $ kitkat —spec 26 Jul 11:03:24 – Generating spec files…… 26 Jul 11:03:24 – Created specfile ‘/path/to/your/app/spec/main.spec.coffee’

If you had an existing coffee file you could copy it to the src/ directory instead of creating the blank coffee file.

1. 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 main.coffee and main.spec.coffee files.

Testing will indicate an initial fail of 1 test because the spec includes a basic example test case which always fails, you will need to modify and add test cases for your next steps.

Dependancies

None in this version, this is heavily simplified from the original kitkat

Third party modules

• optimist - provides a very light weight command line argument processor
• |- wordwrap - required by optimist
• async - some advanced flow control for node.js applications
• stalker - recursive directory monitoring for file changes

Outstanding issues

• Stalker library calls back on modified files it has logged when new files are added, net result is I've had to remove watches before they are added, while this is not clean, it is functional, further review of the stalker library and possible bug report to follow.

• Spec files are created based on the code file name, the only limitation is the spec folder is kept as a flat folder with all specs in the same hierarchy, if a project uses multiple code files with the same name but different subfolders then you would have a conflict in the spec file name.

• Spec file and source file directories need to be populated for anything to really work (of course) but it may not be appearent, best bet is not to run this until you have at least 1 code file in your defined source directory and then run the spec command so that a generic spec file is created. After this all commands should function correctly.

• Many more i'm sure, please report bugs as they are found and code enhancements as they become obvious.

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