Test runner (and community) for Meteor apps. Under heavy development.
##Why Velocity?
The Meteor-provided testing framework, TinyTest, works great for testing packages but doesn't work for apps. Many members of the community created their own solutions but recently we wondered what would happen if we got everybody together and tried to unify our efforts.
Velocity is the result - the unified testing framework for Meteor.
Find out more by watching the Intro to Velocity talk that Robert, Sam, and Mike did at the June 2014 Meteor Devshop!
##Benefits
- officially sanctioned by the Meteor Development Group
- install with one line
- test your whole app, not just packages
- tests run in containers completely isolated from your app
- one report shows all framework results reactively
- easy CI integration
- tests are not published to production
- only executes in dev mode (
process.env.NODE_ENV === "development")
https://trello.com/b/VCmaj73b/velocity-project
The Velocity package itself is not something that you would normally include. Rather you would include the test framework that you would like to use (see below) and it will automatically be added for you.
The velocity package coordinates between test frameworks and provides a common structure for getting test results. Velocity by itself does not perform any tests. To actually test your app, use one or more of the velocity-compatible test frameworks listed below:
- sanjo:jasmine - Write client and server unit and integration tests with Jasmine.
- mike:mocha - A Velocity version of mocha-web. Runs mocha tests in the Meteor context which is great for integration testing.
- clinical:nightwatch - run acceptance tests with automated browsers using the Nightwatch bridge to Selenium
Reporters display test results.
- velocity:html-reporter - Adds an overlay to your app indicating test success/failure (green/red dot in top right). Click dot for test details.
meteor add velocity:html-reporter
We would love to add your framework to the list! Take a look at how some of these interface with velocity and let us know about your framework on the velocity-core google group.
Please see the velocity-wiki for basic instructions on making your test framework work with Velocity.
Also, be sure to check out the documentation for the public API. You can view them in the browser by cloning this repo and then running: open docs/classes/Velocity.html
A few notes on being velocity-compatible:
Please put some sample tests in a directory named sample-tests at the root of your package. These will be used by the velocity-quick-start package and also allows users to click a button in the html-reporter to have them added to their apps.
Please include a way to get more detailed info about your test runs.
One way that we've done it is by having an environment flag that the user can set. Feel free to use VELOCITY_DEBUG if you'd like.
For example, you could write your logging like this:
var DEBUG = process.env.VELOCITY_DEBUG;
DEBUG && console.log('[my-framework] helpful debugging info', someVar);
Use Velocity.registerTestingFramework(frameworkName, options) to register your package as testing framework. You can find a description of the expected arguments in the docs.
Sometimes you just don't what that mirror to start up, maybe the frameworks you have don't need it or you're developing a framework of your own. This is how:
$ NO_MIRROR=1 meteorSometimes things break and its useful to get more debugging info. Most of the test frameworks support some kind of debugging environment variable flag. You can usually see a lot more details about what's happening if you run your app with this command:
$ DEBUG=1 JASMINE_DEBUG=1 VELOCITY_DEBUG=1 VELOCITY_DEBUG_MIRROR=1 meteorError: There was a problem checking out branch: master
Used to be encountered when you referenced the velocity repo directly in smart.json. Was because we tried using a submodule for the example app but meteorite doesn't play well with submodules. If you are still running into this one, see Issue #37 for a fix.
- Clone https://github.com/meteor-velocity/velocity-examples.git
- Create a symlink to your local velocity:core package:
cd velocity-examples/leaderboard-jasmine
mkdir packages
cd packages
# Replace ~/velocity with your path
ln -s ~/velocity velocity:core- Start the velocity example app. It will use your local velocity:core version.
cd ..
meteor- Make code changes
- Commit changes
- Update History.md with summary of changes
- Bump version numbers in package.js, History.md and yuidoc.json
- Execute
yuidoccommand from velocity root path - Commit changes
meteor publish- Tag last commit with the new version
X.X.X - Push to github. Also push the new tag! (
git push --tags)
We have to publish velocity:core for the different architectures (Mac OS, 64-bit Linux and 32-bit Linux).
First publish velocity:core on your development machine with meteor publish. Then you will need machines with the other two architectures. Use meteor publish-for-arch velocity:core@VERSION --release 0.9.4 on a computer with the right architecture. Also see Meteor docs.
We have two naming schemas:
- When the method does something with a resource type:
velocity/<RESOURCE_NAME>/<ACTION> - When the method isn't specific to a resource type:
velocity/<ACTION>
All parts a camelCase and start with a lowercase letter.
##Contributors
We are collaborating with an all-star team on unifying the Meteor testing landscape:
- Sam Hatoum from Xolv.io, author of The Meteor Testing Manual
- Adrian Lanning from Share911, contributor to all things Meteor
- Mike Risse from MadEye, author of mocha-web
- Ronen Babayoff from LaVaina Inc, co-author of Munit
- Abigail Watson from Pentasyllabic, author of Meteor Cookbook, Selenium-Nightwatch
- Robert Dickert from Meteor Boulder, contributor to all things Meteor
- Josh Owens from Differential, author of Testing with Meteor
- Jonas Aschenbrenner, velocity contributor, Jasmine package
Please join our discussions at the velocity-core google group.