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
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.
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'
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.
To start kitkat's automated testing and build mechanism you can do one of the following:
detect and test automatically
detect, test, autospec files not spec'd
If you just need to run a static quick test over all current specs
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
Create and change directory into the folder where your project will reside
$ mkdir myapp $ cd myapp
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/
- 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 —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.
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
- None that I can identify (yet) but please let us know if you find any.
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.
- Keith Benedict
- Edward de Groot
- Stephen Veerman
- Kevin Gamble