karma-jspm
This plugin can now support angular 2.1.1 and JSPM 0.29 beta
See this Test Repo for configurations and examples.
This plugin is originally a fork of Workiva/karma-jspm. Among the additional features, this version utilizes SystemJS to load, transpile, run your tests, and to generate code coverage. Special configurations allow for angular2 testing.
There is no need to preprocess ( pre-transpile ) your code before running tests or to generate a coverage report. Your report may be remapped to the original TypeScript or ES6 source code.
See a sample implementation of this plugin at angular2-jspm-typescript-seed.
You may use this Test Repo to see sample configurations, test scenarios, or to submit a PR to demo bugs. The Test Repo is used for Mac and PC testing.
Installation
Available in npm: npm install karma-uiuxengineering-jspm --save-dev
This plugin assumes you are using jspm in your project. You will
need to have a config.js
in the root of your project (though this
is configurable) as well as a jspm_packages
directory containing
systemjs and the es6-module-loader.
Configuration##
For simple architectures, minimal configuration is needed.
karma.conf.js
Include this plugin in your frameworks:
frameworks: 'jspm' 'jasmine'
If you want to register the plugin with karma ( not required ):
plugins: 'karma-uiuxengineering-jspm' 'karma-jasmine' 'karma-chrome-launcher'
Set basePath
of your karma config to the the directory where
you will serve the development of your app.
config
loadFiles DEPRECATED
Use files below. LoadFiles and serverFiles properties were used to distinguish with patterns karma should use to load files into the browser. SystemJS loads all app and test files in the browser, so there is only one karma pattern that works.
This pattern is configured by default with the files
property.
In case you are wondering, this is the pattern:
pattern: 'relative/path/file.ts' // Not using <script> tags to load files, systemjs is loading them. included: false // Karma is serving the file served: true // Not serving from the file system, serving from karma server nocache: false // Re-test if file changes watched: true
serveFiles DEPRECATED
Use files below.
See loadFiles above for deprecation explanation.
files
Required
Default: undefined
The jspm.files
configuration tells karma-jspm which files should
be dynamically loaded via systemjs.
glob 7.x is supported.
You should not include these in the regular karma files array. karma-jspm takes care of this for you by adding them with the correct karma object configuration.
config
For more complex architectures, additional configurations may be necessary.
JSPM 0.17 Beta Config files - Notes
Config files are loaded in this following order, regardless of which file may be excluded:
browserConfig, devConfig, nodeConfig, jspmConfig
browserConfig is first because it normally contains "baseURL", which SystemJS throws an error if it is not in the first config called.
jspmConfig is last because it normally contains mapping, packages, and transpiler information.
As you will see in the Test Repo there are two transpilers.
The default ( primary ) is the one which is assinged to the transpiler
property ( babel in the test repo ).
The additional (secodndary) just has configuration options ( TypeScript in the Test Repo ). In my expirements the secondary MUST be
in the same file/config which the package is defined to use it as a loader.
browserConfig
JSPM 0.17 Beta
Optional
Default: undefined
For JSPM 0.17 Beta, you can to specify jspm.browser.js
.
config
devConfig
JSPM 0.17 Beta
Optional
Default: undefined
For JSPM 0.17 Beta, you can to specify jspm.dev.js
.
config
nodeConfig
JSPM 0.17 Beta
Optional
Default: undefined
For JSPM 0.17 Beta, you can to specify jspm.node.js
file.
config
config DEPRECATED
Use ```jspmConfig````.
config
has been deprecated to align with jspm 0.l7 naming conventions.
By default jspm names the base config jspm.config.js
.
jspmConfig
Optional
Default: parsed from package.json
You may have named your jspm config.js
. The package.json configuration
for jspm beta may change; if you have issues, provide the path to
your config file.
config
packages
Optional
Default: parsed from package.json
You may have named your jspm_packages
directory to something else.
The package.json configuration for jspm beta may change; if you have
issues, provide the path to your packages directory.
config
useBundles
Optional
Default: false
By default karma-jspm ignores jspm's bundles configuration. To re-enable
it, specify the useBundles
option.
config
paths
Optional
Default: undefined
Depending on your framework and project structure it might be necessary
to override jspm paths for the testing scenario.In order to do so just
add the paths
property to the jspm config object in your
karma-configuration file, along with the overrides:
jspm: paths: '*': 'yourpath/*.js' ...
stripExtension
Optional
Default: undefined
By default the plugin will strip the file extension of the js files.
To disable that, specify the stripExtension
option:
jspm: stripExtension: false
cachePackages
Optional
Default: undefined
Most of the time, you do not want to cache your entire jspm_packages directory, but serve it from the disk. This is done by default, but can be reversed as follows:
jspm: cachePackages: true
adapter
Optional
Default: undefined
By default, an adapter implementing karma.start()
is provided to
launch unit tests. Other plugins may override karma.start
causing
issues with this plugin. You may use a custom adapter to resolve these
issues. See the provided default adapter for an example implementation:
jspm: adapter: 'youradapter.js'
testWrapperFunction
Optional
Default: undefined
Some test implementations require the tests ( describe blocks ) to be wrapped in a function. Set the name of the wrapper function.
jspm: testWrapperFunction: 'main'
preloadBySystemJS
Optional
Default: undefined
SystemJS loads files from the jspm_packages
directory ( or your
named directory ) by concatenating the file and version number that
is mapped in the jspm.config.js file. So loading af file with SystemJS
with the path string "zone.js/dist/zone.js" would actually load with
the path similar to "jspm_packages/npm/zone.js@0.6.12/dist/zone.js".
You can use SystemJS to pre-load files before tests are run the same as you would in your app, rather than using karma to load the files by manually configure the paths.
Provide an array of path strings that are the same as you would import them in your app. They will load in same order as your array.
see Angular 2.0 related files pre-loaded.
jspm: preloadBySystemJS: // Polyfills 'es6-shim' 'core-js/client/shim.min.js' 'reflect-metadata/Reflect.js' // Test Assistance 'zone.js/dist/zone.js' 'zone.js/dist/long-stack-trace-zone.js' 'zone.js/dist/async-test.js' 'zone.js/dist/fake-async-test.js' 'zone.js/dist/sync-test.js' 'zone.js/dist/proxy.js' 'zone.js/dist/jasmine-patch.js' // TestBed.initTestEnvironment '@angular/core/testing' '@angular/platform-browser-dynamic/testing'
Code Coverage
A coverage Instrumenter is provided with a SystemJS hook in the browser using @guybedford's example from his blog. Similar to the karma-coverage plugin, you set the preprocessor to 'jspm'. This does NOT transpile files, but only selects which files to include in your coverage report.
preprocessors: 'app/**/!(*.spec).ts': 'jspm'
The reporter works the same as other karma reporters.
reporters: 'jspm'
remap
Optional
Default: false
Configure the output of the reports using coverageReporter property. Set
remap
to true to map the coverage reports to the original typescript
or es6 files.
coverageReporter: // map coverage to source typescript or es6 files. remap: true dir: process + '/coverage' reporters: // will generate html report type: 'html' // will generate json report file and this report is loaded to // make sure failed coverage cause gulp to exit non-zero type: 'json' file: 'coverage-final.json' // will generate Icov report file and this report is published to coveralls type: 'lcov' // it does not generate any file but it will print coverage to console // a summary of the coverage // {type: 'text-summary'}, // it does not generate any file but it will print coverage to console // a detail report of every file type: 'text'
Angular2 Configurations
adapter
Required
Set to: 'angular2'
If you are using angular2, specify 'angular2' as your adapter, and an a adapter specific to angular2 tests will be used.
jspm: adapter: 'angular2'
testWrapperFunctionName
Optional
Default: 'main'
Angular2 tests may implement a wrapper function. By default, the
wrapper function is main()
. You can override this with
either another function name for an empty string if a wrapper
function is not desired.
jspm: testWrapperFunctionName: 'nameOfFunction'
preloadBySystemJS
Optional
Default: see below
For Angular2 testing, SystemJS will automatically pre-load the following files before tests are run, so they are ot necessary to load in the karma config.
// Polyfills 'es6-shim' 'core-js/client/shim.min.js' 'reflect-metadata/Reflect.js' // Test Assistance 'zone.js/dist/zone.js' 'zone.js/dist/long-stack-trace-zone.js' 'zone.js/dist/async-test.js' 'zone.js/dist/fake-async-test.js' 'zone.js/dist/sync-test.js' 'zone.js/dist/proxy.js' 'zone.js/dist/jasmine-patch.js' // TestBed.initTestEnvironment '@angular/core/testing' '@angular/platform-browser-dynamic/testing'
If you want to change the pre-load file list above, you may override
with the preloadBySystemJS
config.
jspm: preloadBySystemJS: 'fileA.js' 'fileB.js'