Miss any of our Open RFC calls?Watch the recordings here! »

mimosa-ember-test

1.1.0 • Public • Published

mimosa-ember-test

Overview

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 require@3.2.0. 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.

Usage

  • 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)
  • Add 'ember-test' to your list of modules. Mimosa will install the module for you when you start up.
  • Check the default config to verify it syncs with your app. If it doesn't, you'll have a few things to configure/update.
  • Write tests! By default ember-test considers any file compiled/copied to watch.compiledDir that ends with -spec.js, _spec.js, -test.js or _test.js a test.

Functionality

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.

Vendor Assets

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.

Generated Test Assets

ember-test also generates test scaffold assets for each app configured in your project. Those assets include

  • testem.json file which configures how testem runs
  • runner.html which is the file loaded in the browser to start the tests
  • test-main.js which uses require.js to load both the vendor testing assets and the application tests before then kicking off the tests
  • test-variables.js which contains JavaScript variables for your require.js config and an array of paths to your tests.

Running

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.

Command

mimosa testscript

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.

Running Tests in Development Mode

./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.

Running Tests in Continous Integration Mode

./test.sh ci

This will launch the tests in the browsers configured for continuous integration (PhantomJS by default).

Running Tests for Multiple Apps

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.

Default Config

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.

Install

npm i mimosa-ember-test

DownloadsWeekly Downloads

0

Version

1.1.0

License

MIT

Last publish

Collaborators

  • avatar