Customizing Karma with Configuration

Karma’s plugins, adapters, and preprocessors are also node modules that can be installed via the npm registry.

Karma is configurable via the karma.conf.js file. There are a few settings that we can configure in this file in order to customize the testing environment.

Karma loads the files that have been included within the “files” array entry. Since this boilerplate is using Webpack and the module system, these files are loaded via a single script file: spec-bundle.js. This ensures that all the required dependencies of the project have been loaded successfully.

The “preprocessors” entry allows us to define a processing tool for each entry that has been defined in the “files” section. In our case, the files that have been loaded should be compiled using Webpack and its relevant Webpack test configuration file (the “webpack” entry is a custom entry key that is being read only by the karma-webpack plugin). In addition to that, multiple preprocessors can be run on each entry in our boilerplate. The “coverage” and “sourcemap” preprocessors are useful for creating a coverage summary for the test’s results and a source map dictionary file for the typescript files of the application’s code. The “coverage” preprocessors create a new directory with the results formatted as a mini HTML website (this is defined in the “coverageReporter” entry).

Karma-Supported Frameworks

Karma is agnostic for several values within the configuration file. It can run the tests on any browser that has had its launcher loaded as a plugin. Most browsers have a launcher. In addition to that, tests can be run on multiple browsers simultaneously. This is defined in the “browsers” entry.

Karma is also agnostic to the testing framework that is being used for writing and asserting tests. Each framework should be plugged into karma with a dedicated adapter. In our boilerplate, we are using Jasmine. It’s also the default testing framework being used by the Angular team and is documented on the documentation website of Angular (https://​angular.​io/​docs/​ts/​latest/​guide/​).

Configuring Karma’s Output Results

In order to display the results of tests, karma uses the “reporters” entry to figure out who or what it should report the result to. A reporter is usually a script that sends the result to an output device. This output device can be the terminal, an HTML file, or a Continuous Integration (CI) server (i.e., Travis-ci, Jenkins). Karma includes the default reporters “dots” and “progress.” Our boilerplate is configured to use the default reporter “mocha,” which prints the description of each test (or, more precisely, a spec) in a green color with a success or error indicator (which will be then printed in a red color). In addition, the “coverage” reporter is used in conjunction with its preprocessor to output a coverage result for the whole application.

Karma’s Test Process Modes

Two entries that are important to notice are “singleRun” and “autoWatch.” The “singleRun” entry tells karma to run all the tests exactly once and then exit the process and terminate the test task. This is useful when the test process is integrated with a CI such as “Travis-CI” or “Jenkins”. If this entry is set to false, then the process of the test runs the tests once and then hangs and waits for another command; the task is terminated. This usually goes along with the “autoWatch” entry, which tells karma to watch for changes within the files that have been loaded. If set to true, karma will run the tests again as long as the process is alive. It is disregarded when “singleRun” is set to true.

There are more settings that have been defined within the karma.conf.js file; however, we overviewed the important ones for our needs in this book. There is very good documentation on karma’s website as well as other useful information. Table 2-1 summarizes the settings relevant to the karma.conf.js boilerplate that we’ll work with in this book.

Entry

Via “Entry,” we can define bundles that Webpack will start from; it eventually produces bundled files. This is a simple key-value object in which the key represents the name of the output file and the value represents the starting point for bundling the file and its dependencies.

The following three files are produced in our boilerplate:

1. polyfills – required libraries for adding missing functionality to old browsers (like es6 features and others)

2. vendor – third-party library files, such as Angular’s packages, RxJS, ngrx’s files, and others

3. main – the actual code of the application that we write on our own

entry: {

      'polyfills': './src/polyfills.browser.ts',
      'vendor':    './src/vendor.browser.ts',
      'main':      './src/main.browser.ts'

    },

Resolve

“Resolve” is a group of settings that can be used to configure how files are resolved when required. Since we’re going to use Typescript to write code and then load files with a .ts extension, this can be useful.

resolve: {

      /*
       * An array of extensions that should be used to resolve modules.
       *
       * See: http://webpack.github.io/docs/configuration.html#resolve-extensions
       */
      extensions: ['', '.ts', '.js', '.json'],

      // Make sure root is src
      root: helpers.root('src'),

      // remove other default values
      modulesDirectories: ['node_modules'],

    },

Module: pre-loaders, loaders, and post-loaders

The “module” setting is one of the most useful settings and is an interesting option in Webpack. This setting is what makes Webpack a module loader that is agnostic to the extension of the module.

A loader, in Webpack’s world, is a kind of plugin that assists Webpack in importing a file to the application and parsing it as it should be. A loader is defined using a simple json object. For example, in order to be able to load HTML files as strings, we can use raw-loader and define it like so:

{
          test: /.html$/,
          loader: 'raw-loader',
          exclude: [helpers.root('src/index.html')]
}

This json object is added to the “loaders” array and provides the following instructions for Webpack:

1. test – a regular expression that applies this loader when one of the import or require statements points to a file with a .html extension

2. loader – Use one or more loaders to load this (html) type of file; in this case, use raw-loader only.

3. exclude (optional) – Ignore these paths/files before you try to load the file.

Now you can understand how Webpack can treat any kind of file as a module by using any type of loader.

The “pre-loaders” array is a collection of loaders that process the loaded files before the primary loaders are applied. The “post-loader” array is a collection of loaders that process the loaded files after the pre-loaders and loaders are applied.

There are several methods by which to apply multiple loaders to the same type of file.

1. Array of strings – each loader is defined separately and is applied by the order of the array; i.e., loaders: ['to-string-loader', 'css-loader']

2. Separated by “!” – each loader is separated by “!” in one string. Webpack applies the loaders from right to left; i.e., loaders: 'to-string-loader!css-loader'

Plugins

“Plugins ” is a collection of processors that operates on the bundles after both the loading and its processors are complete. It’s like post-processing the output result of Webpack’s file bundling.

Webpack’s object, “webpack,” includes several built-in plugins. Usually, a plugin is the result of a newly created object, such as:

new webpack.optimize.CommonsChunkPlugin({
        name: ['polyfills', 'vendor'].reverse()
})

The order of the plugins in this array doesn’t matter (unless plugins apply to the same bundle or for a common goal).

Similar to loaders, a plugin is usually a function that is applied by Webpack’s compiler.

Node

The “Node” settings supply polyfills or mocks for various objects in the node environment.

Output

The “Output” setting is the counterpart to “Entry.” Contrary to the entry setting, there should only be one output setting; this affects all entries. Let’s review some of the options in this setting. The output file’s extension is a JavaScript (*.js) extension file.

• filename – We can set the name of the output file by using brackets. [name].bundle.js is an example of a technique used for template-like variables that should be applied to each entry (when multiple entries are configured).

• path – This is the target directory where the file should be placed at the end of compilation.

• sourceMapFilename – We can set the template name for the sourcemap file that is generated: [file].map.

For more options, navigate to https://webpack.github.io/docs/configuration.html#output .

devtool

This setting allows Webpack to create source maps to the generated files in various ways. A source map is a standard way to interpret transpiled code to its origin. This feature enables us to view the original source code as it is written (i.e., in Typescript) in the browser’s developer tool.

Webpack’s “devtool” setting enables few useful values. Each setting has its pros and cons in terms of build performance, rebuild performance, quality of the generated code, and production support. These configurations are shown in Table 2-2.

This concludes our introduction to Webpack and its responsibilities in our boilerplate.

app.module.ts

This file is the main module. Eventually, Angular bootstraps it as the application in main.browser.ts. We will import other modules in this file and define them as needed. A good example of a module is the HttpModule.

app.component.ts

This is the main application component. Its template usually outlines the main structure of the application. It can include high-level components (container components) without any input properties. These high-level components can be feature modules.

In Echoes Player, the “app.component.ts” template includes some high-level components and one route outlet component to which a different component is rendered when the route changes.

Store Directory

This module defines the core store module that the app can use. The store incorporates ngrx/store as the reactive state-management solution.

Eventually, this directory will include directories of reducers and actions. Each directory defines a reducer for handling its state updates or actions that will be used as “tokens” to dispatch a state update.

// my-reducer.reducer.ts
import { ActionReducer, Action } from '@ngrx/store';
import { MyReducerActions } from './my-reducer.actions';

export interface SomeInterface {
    items: Item[],
    filter: string
}
let initialState: SomeInterface = {
    items: [],
    filter: ''
}
export functoin MyReducer (state: SomeInterface = initialState, action: Action): ActionReducer<SomeInterface> {

    switch (action.type) {
        case MyReducerActions.ADD_ITEMS:
            return Object.assign({}, state, { items: [...items, ...action.payload] });

        case MyReducerActions.UPDATE_FILTER:
            return Object.assign({}, state, { filter: action.payload });

        default:
            return state;
    }
}

Effects Directory

This directory includes various side effects that result from some of the actions that we’ll work with. A side effect in this context is usually a “chain” of actions—a flow where a certain action should always followed by another action.

An effect is defined with the decorator @Effect:

// some-effect.effect.ts
@Effect()
addItemsReady$ = this.actions$
    .ofType(MyReducerActions.ADD_ITEMS)
    .map(action => action.payload)
    .switchMap(items => this.someServiceInfo.fetchMoreData(items)
      .map(items => this.myReducerActions.queueItems(items))
      .catch(() => Observable.of(this.myReducerActions.addItemsFailed(media)))
    );

This @Effect decorator reacts to the ADD_ITEMS action. Whenever this action is dispatched, there should be a side effect—a call to the fetchMoreData method, which results in new observable objects. This is why we use switchMap to “listen” to the new stream. When this stream is resolved, the second action object should be invoked by the myReducerActions action creator and handled by the MyReducer reducer. If something goes wrong, a good practice is to define a “catch” handler that dispatches an action object with addItemsFailed.

Using a layer of effects is useful for several use cases. In this layer, we can initiate requests in order to update a backend service. It is also useful for updating or adding additional data to a state (think of paging lists of data). Beyond that, it promotes the perspective of designing services as “pure” stateless objects, allowing us to use it for fetching and updating data from/to a backend service while not keeping the state in these objects, but rather keeping it in our store.

We’ll go into more depth with effects later in this book so we can understand how they contribute to the structure and flow of logic in our application (or any other application).

Services Directory

This directory includes the core services of this application. Usually, feature modules should consume these services in order to interact with external data API (YouTube’s API, in this case).

Most of the code is already written for these services; however, we’ll update these as we go along with the book in order to experiment and understand reactive programming with services in Angular.

Other Directories (home)

In this level of directories, next to the app.*.ts files, we’ll create container components (smart components) for those components that have access to the application’s services and core features.

The HomeModule includes the home component, which is an example of such a container component. It stands on its own and connects to the store and services of the application.

We’ll create several smart components, each of which will eventually be activated via routes that we’ll create. Each smart component may define its own nested routes to which other components are attached.

To create modular and maintainable components, it is very useful to create smaller, nested components within the smart component directory (not necessarily attached to nested routes).