A Mimosa module for testing Ember.js applications with QUnit.
This is a Mimosa module that integrates a qunit/testem test scaffold into your RequireJS/EmberJS Mimosa application.
Client JavaScript testing requires a good deal of configuration to set up, as well as plenty of research and trial and error before you can start writing tests. Ember.js apps require a bit more than other apps to get set up correctly.
The goal of this module is to keep test setup to a minimum. Out of the box it requires no configuration. The module writes its own configuration derived from your project. In most cases you can include the module and start writing tests.
This module incorporates QUnit, ember-qunit, Chai, chai-qunit, Sinon, Testem and PhantomJS.
For more information regarding Mimosa, see http://mimosa.io
NOTE: This module requires Mimosa 2.3.14
to function properly. If this is an issue, please file a GitHub request to address.
NOTE: Version 1.0.0
of this module requires version 3.2.0
of mimosa-require. Update your modules
to [email protected]
. If you can't use 3.2.0
, that is ok, but validation errors (that will likely not really be errors) might become a nuisance.
npm install -g phantomjs
(If you are on Windows, this will not install phantomjs properly. You will need to download phantomjs from the site and add the executable to your PATH
)'ember-test'
to your list of modules. Mimosa will install the module for you when you start up.ember-test
considers any file compiled/copied to watch.compiledDir
that ends with -spec.js
, _spec.js
, -test.js
or _test.js
a test.ember-test
does all of its work in the .mimosa/emberTest
folder (location configurable). It wants to keep all the scaffolding, test setup and test libraries out of your application.
ember-test
expects QUnit, ember-qunit, Chai, chai-qunit, Sinon, and require.js to be available. ember-test
fabricates test runners and test scaffolding that depends on those libraries.
By default, ember-test
will use Bower to incorporate those vendor test assets. This module understands how mimosa-bower works, and coordinates with mimosa-bower to get these specific tests assets into the right location inside .mimosa/emberTest
. If you do not change the default away from Bower, ember-test
will verify you have a bower.json
and check that file to make sure the right libraries are present. If they are not, ember-test
will stop Mimosa from starting up with a validation error.
The following is an example of the update necessary for your bower.json
. If you already have requirejs
in your dependencies
you do not need to include it here. This documentation may fall out of date with versions.
"devDependencies": {
"qunit": "1.18.0",
"requirejs": "2.1.14",
"sinonjs": "http://sinonjs.org/releases/sinon-1.15.0.js",
"ember-qunit-builds":"0.4.0",
"chai": "3.0.0",
"chai-qunit":"0.2.1"
}
If you prefer to not use Bower, set bowerTestAssets
to false
and ember-test
will copy in versions of the vendor files that it maintains.
ember-test
also generates test scaffold assets for each app configured in your project. Those assets include
testem.json
file which configures how testem runsrunner.html
which is the file loaded in the browser to start the teststest-main.js
which uses require.js to load both the vendor testing assets and the application tests before then kicking off the teststest-variables.js
which contains JavaScript variables for your require.js config and an array of paths to your tests.When mimosa build
starts up ember-test
will write all the assets and execute your tests. If all the tests pass, a message will indicate that on the console and you will not be notified any other way. If tests fail, the console will have the details of the test failure and a Growl message will get sent letting you know a test has broken.
Executing mimosa testscript
at the root of your project will drop a platform appropriate script named test.sh
or test.bat
that you can use to execute your testem tests directly.
Run mimosa testscript --help
to see available options.
NOTE: You will need to have Testem installed prior to running the generated script: npm install -g testem
.
./test.sh
This will launch the tests in the browsers configured for development (Chrome and Firefox by default) and let you interact directly with Testem's text-based UI.
You will want to run this in conjunction with mimosa running (mimosa watch
), so that your tests get compiled/copied to the correct location and the configuration gets updated. To run both watch
and execute your tests, try mimosa watch & ./test.sh
.
./test.sh ci
This will launch the tests in the browsers configured for continuous integration (PhantomJS by default).
If you have configured emberTest
for multiple Ember applications within your project, you can run the script to execute the tests for one app at a time:
Usage: ./test.sh [test_number]
[1] test configuration for one app
[2] test configuration for another app
In CI mode, mimosa will run the tests for each application in sequence.
emberTest: {
apps: [{
testLocation: "tests",
testAppFactory: "create_test_app",
javascriptsPaths: [],
stylesheetPaths: [],
requireConfig: null
}],
bowerTestAssets: true,
emberAMDPath: "ember",
executeDuringBuild: true,
executeDuringWatch: false,
safeAssets: [],
specConvention: /[_-](spec|test)\.js$/,
assetFolder: ".mimosa/emberTest",
testemConfig: {
"launch_in_dev": ["Firefox", "Chrome"],
"launch_in_ci": ["PhantomJS"]
}
}
testemSimple: {
configFile: emberTest.assetFolder + "testem.json",
port: null,
watch: [],
exclude:[],
}
#####apps array of objects
The configuration for all the ember applications in your project. Can be just a single app.
#####apps.testLocation string
The path, relative to watch.javascriptDir
where this ember app's test assets live
#####apps.testAppFactory string
The path, relative to testLocation
, where a file exporting a function capable of generating a test-ready version of this ember app is located
#####apps.javascriptPaths array of strings
The paths, relative to the root of the project, of any additional javascript files that need to be included in the test runner.
#####apps.stylesheetPaths array of strings
The paths, relative to the root of the project, of any additional stylesheets that need to be included in the test runner.
#####apps.requireConfig object or function
The configuration used by require.js in your tests for this app. By default this does not need to be provided. ember-test
will derive this from your project. To see what it derives, look at .mimosa/emberTest/test-variables.js
. If an object is provided, it will be used instead of the derived config. If a function is provided, that function will be called and provided the derived config. This gives you a chance to just tweak a few properties if that is all that is needed.
#####bowerTestAssets boolean
When set to true
this module will attempt to use mimosa-bower to load in vendor test assets
#####emberAMDPath string
The AMD path for ember. This is often aliased to "ember"
, so that is the default
#####executeDuringBuild boolean
Determines whether mimosa will automatically execute the tests during build.
#####executeDuringWatch boolean
Determines whether mimosa will automatically execute the tests during watch as files are changed. Once a decent number of tests exist for your project, you may not want this to be set to true
as tests can take awhile.
#####safeAssets array of file names
You may choose to alter the assets that Mimosa writes, for instance to use your own version of qunit. Mimosa by default will overwrite the files in this folder. If you don't want your file overwritten, add the name of the file to this array. Just the name, no paths necessary.
#####specConvention regex
This is the regex ember-test
uses to identify your tests. It'll run this regex against every compiled file to determine if it is indeed a test and if it is, ember-test
will include it in the list of tests to be run.
#####assetFolder string
The folder ember-test
places its assets. It is relative to the root of your project.
#####testemConfig object
Testem configuration that ember-test
uses as default. This default defines the browsers to run the tests in. ember-test
amplifies this with a few other computed properties
#####testemSimple object
ember-test
wraps the mimosa-testem-simple module. It overrides the testemSimple.configFile
property to point the testem.json
files it creates. The other testem-simple config can be updated/modified directly. The config for testem-simple allows you to tweak how testem is run.