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.set({
    
    basePath: './',
    
    jspm: {
        // Edit this to your needs
        loadFiles: ['src/**/*.js', 'test/**/*.js']
    }
}

####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.set({
    
    basePath: './src/browser',
    
    jspm: {
        // glob 7.x patterns supported 
        files: ['app/**/!(*.e2e-spec).ts']
    }
}

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.set({

    basePath: './src/client',
    
    jspm: {
        // relative to basePath in karma config
        browserConfig: "path/to/myJspmBrowser.js"
    }
}    

####devConfig JSPM 0.17 Beta
Optional
Default: undefined

For JSPM 0.17 Beta, you can to specify jspm.dev.js.

config.set({

    basePath: './src/client',
    
    jspm: {
        // relative to basePath in karma config
        devConfig: "path/to/myJspmDev.js"
    }
}    

####nodeConfig JSPM 0.17 Beta
Optional
Default: undefined

For JSPM 0.17 Beta, you can to specify jspm.node.js file.

config.set({

    basePath: './src/client',
    
    jspm: {
        // relative to basePath in karma config
        nodeConfig: "path/to/myJsonNode.js" 
    }
}    

####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.set({

    basePath: './src/client',
    
    jspm: {
        // relative to basePath in karma config
        config: "path/to/myJspmConfig.js"
    }
}    

####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.set({

    basePath: './src/client',
    
    jspm: {
        // relative to basePath in karma config
        packages: "path/to/my_jspm_modules/"
    }
}    

####useBundles Optional
Default: false

By default karma-jspm ignores jspm's bundles configuration. To re-enable it, specify the useBundles option.

config.set({

    basePath: './src/client',
    
    jspm: {
        useBundles: true
    }
}

####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/[email protected]/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.cwd() + '/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']
}