setup.md

« return to the manuals

Setup Instructions

In the following, we describe a setup using webpack, because this setup is supported out-of-the-box by LaxarJS and LaxarJS Mocks. Other module loaders and bundlers can be integrated by interfacing with LaxarJS Tooling, but that advanced use case is not covered here (the API docs will help you).

General project Setup

First, you need to add LaxarJS Mocks as a dependency to your project:

npm install --save-dev laxar-mocks

It is recommended to put your widget spec tests into files with the extension .spec.js within a spec folder of each widget that you would like to test. For example, a widget called my-widget would come with a spec/my-widget.spec.js. This allows you to use the webpack rules configuration for automatically loading all widget specs through the LaxarJS Mocks spec-loader.

Here is an example excerpt for use in a webpack.config.js:

module.exports = {
   // ... entry, resolve, ...
   module: {
      // ... other module config ...
      rules: [
         // ... more rules ...
         {
            test: /spec\/.*\.spec\.js$/,
            loader: 'laxar-mocks/spec-loader'
         }
      ]
   }
};

Of course, you can also use .jsx or .ts spec tests if your other loaders are setup accordingly.

Running Tests using Karma

If webpack is configured as above, you can run spec tests with karma by using karma-webpack to preprocess your specs.

Here is an example excerpt for use in a karma.config.js:

const webpackConfig = require( './webpack.config.js' );
// `entry` for tests is generated by karma-webpack:
delete webpackConfig.entry;

module.exports = function( config ) {
   config( {
      // ... other karma settings ...
      frameworks: [ 'jasmine' ],
      files: [ 'path/to/widget/spec/*.spec.js' ]
      preprocessors: {
         'path/to/widget/spec/': [ 'webpack', 'sourcemap' ]
      },
      webpack: webpackConfig
   } )
};

To get all the settings right, especially when you are testing many widgets in the context of a development project, it is probably simpler to get started using the Yeoman Generator for LaxarJS 2.x, which automatically prepares a working karma setup for your project.

Running Tests in the Browser

Karma is great to run all of your tests each time you make a change to your project, for example in a Continuous Integration setup. However, once you get down to debugging individual test cases, possibly trying to diagnose browser-specific problems, the ability to run your spec test within a web browser is invaluable. Not only can you use the Jasmine HTML runner to drill down to individual test cases, but the powerful developer tools of modern browsers are at your disposal.

To help running widget spec tests in the browser without copy/pasting a lot of brittle boilerplate HTML, projects can use the Jasmine HTML Runner Plugin for Webpack which is maintained by the LaxarJS team. Again, projects started with the LaxarJS 2 Yeoman Generator are configured to work with the HTML runner plugin out-of-the-box: To build and to browse the HTML, run npm run browser-spec and then open your web browser at http://localhost:8180/spec-output/ to view the tests served by the webpack-dev-server.

For a manual setup, you will need to use a webpack configuration that configures the HTML spec runner:

const config = {
   // ... your webpack configuration, including the spec-loader config shown above ...
};

const WebpackJasmineHtmlRunnerPlugin = require( 'webpack-jasmine-html-runner-plugin' );
config.entry = WebpackJasmineHtmlRunnerPlugin.entry( `path/to/widgets/**/spec/*.spec.js` );
config.output = {
   path: path.resolve( path.join( process.cwd(), 'spec-output' ) ),
   publicPath: '/spec-output/',
   filename: '[name].bundle.js'
};

You should probably put the HTML spec runner configuration into a dedicated webpack configuration file used for testing, or hide it behind an environment variable, as the generator project does.