calmjs.dev 2.2.2

Introduction

Python packages can contain arbitrary resource files, which can include JavaScript sources. This situation is commonly found in packages that provide frontend functionalities that enhance user experience that require interactions with a related backend Python code running on the server provided by the given package. In order to facilitate the testing of those JavaScript code from those Python packages, commonly Node.js packages and frameworks are often used to achieve this.

Typically, for the management of this dependency, this often require two or more separate package management systems that are not properly aware of each other, resulting in often cumbersome linkage or needless duplication of packages installed on a given system. Moreover, the configurations files for the Node.js/JavaScript package dependencies, along with the building of artifacts and testing of the JavaScript provided by those Python packages are very specific to the given project and generally not portable. If multiple such packages are required for a downstream Python project, the scripts and definition files for building of artifacts and testing generally have to be manually modified, which is often a very aggravating and error-prone process.

The Calmjs framework, however, provides the means for Python packages to declare the JavaScript modules they are to export, and this package, calmjs.dev, provides the means to consume those information such that the JavaScript tests declared within those Python packages can be executed without having to manually construct and verify the paths to the source and tests files, no matter where they are within the environment, provided they are properly declared through the Calmjs framework. The tests can then run either against the JavaScript sources provided by the Python package through the artifact generation framework, or against prebuilt artifacts that contain those functionalities. Naturally, the support for the artifact generation framework requires integration with the Calmjs framework. Currently, generation of AMD artifacts is supported using the calmjs.rjs, and the generation of webpack artifacts supported through the calmjs.webpack package.

Features

• Provides a set of commonly used development tools that are commonly used for testing JavaScript code. In brief, these include:

  karma

  Test runner for running tests included with packages against the JavaScript code contained there.

  mocha

  A JavaScript test framework for writing unit tests for node.js or the browser.

  phantomjs

  A headless webkit with JavaScript API capable of interfacing with karma; this enables the running of integration JavaScript tests.

  sinon

  A set of spies, stubs and mocks for JavaScript, for working with unit testing frameworks.

  Plus other integration packages that get them to work with each other, namely the various karma-* packages for integration with karma. For full details on the environment that will be installed through the calmjs framework, the command calmjs npm calmjs.dev can be invoked to view the package.json once this package is installed into a Python environment. For installation, please refer to the following section.

• Through the use of the calmjs module registry system, Python packages can declare JavaScript sources that can be passed through specific toolchains that build them into deployable artifacts. The calmjs.dev package provide a common framework for the generation of configuration files for the execution of tests through the karma test runner.

  The usage of this is typically through the calmjs runtime system.

Installation

As the goal of calmjs.dev is to integrate Node.js development tools into a Python environment, both Node.js and npm are required to be available within the target installation environment; if they are not installed please follow the installation steps for Node.js appropriate for the target operating system/environment/platform.

Naturally, since this is achieved through calmjs, it will need to be available in the target installation environment; however, this is achieved simply by installing calmjs.dev through pip from PyPI.

$ pip install calmjs.dev

$ pip install git+https://github.com/calmjs/calmjs.git#egg=calmjs

$ calmjs npm --install calmjs.dev

$ python -m unittest calmjs.dev.tests.make_suite

$ CALMJS_TEST_ENV=. python -m unittest calmjs.dev.tests.make_suite

Usage

The default tool is meant to provide an injectable runtime that sits before a calmjs toolchain runtime that is responsible for the generation of deployable artifacts, such as AMD bundles through RequireJS. Currently, the standard way to use this package is to use it in conjunction of the calmjs.rjs toolchain runtime. For instance, one might execute the r.js tool through calmjs.rjs like:

$ calmjs rjs example.package

The above command would package all the JavaScript code provided by the Python package example.package into an AMD bundle artifact through r.js. As the example.package may also provide tests for its JavaScript code (naturally written in JavaScript), it may be executed through the karma test runner provided by the selected package. The command is as simple as adding karma before the toolchain runtime, like:

$ calmjs karma rjs example.package

This would apply a test advice to the rjs toolchain runtime and invoke it. Normally, before the bundling is done, the tests will be executed against the transpiled sources in the build directory. Note that the test advice is also implemented by calmjs.rjs to ensure that this testing workflow is properly integrated. Likewise for calmjs.webpack, where its support for webpack is also provided through a similar mechanism such that the following command will execute the tests for the package through the typical webpack method of karma invocation:

$ calmjs karma webpack example.package

To run tests against pre-generated artifact files, calmjs.dev provides a surrogate toolchain runtime specific for the karma command that may be used to achieve this purpose. For example, given an artifact file (e.g. bundle.js), it is possible to test whether it correctly included JavaScript code generated/provided by example.package using tests provided by the same package with the following command:

$ calmjs karma run \
    --artifact=bundle.js \
    --test-with-package=example.package

However, for more complicated toolchains and packages this will probably not work, as the generation of these artifacts typically involve extra optional advices that have been added. To address that, one may apply the --toolchain-package flag which serves a similar purpose as the --optional-advice flag for certain toolchains. For calmjs.rjs, this is necessary. The full command may be like so:

$ calmjs karma run \
    --artifact=bundle.js \
    --test-with-package=example.package \
    --toolchain-package=calmjs.rjs

Likewise for webpack; if the selected artifact file is generated through calmjs webpack, it may be tested using the following:

$ calmjs karma run \
    --artifact=bundle.js \
    --test-with-package=example.package \
    --toolchain-package=calmjs.webpack

As with all calmjs tools, more help can be acquired by appending -h or --help to each of the runtime commands, i.e. calmjs karma -h or calmjs karma run -h. Replacing the -h flag with -V will report the version information for the underlying packages associated with the respective runtime used.

$ calmjs rjs nunja
$ calmjs karma --coverage --artifact=nunja.js --cover-test \
    rjs nunja.stock --sourcepath-method=explicit

$ calmjs artifact karma example.package

$ calmjs artifact karma example.package \
    --test-with-package example.dependent

Troubleshooting

The following may be some issues that may be encountered with standard or typical usage of calmjs.dev.

$ calmjs npm --install calmjs.dev ...

$ calmjs npm --install nunja[dev]

$ python setup.py egg_info

Contribute

• Issue Tracker: https://github.com/calmjs/calmjs.dev/issues

• Source Code: https://github.com/calmjs/calmjs.dev

Legal

The Calmjs project is copyright (c) 2016 Auckland Bioengineering Institute, University of Auckland. calmjs.dev is licensed under the terms of the GPLv2 or later.

2.2.2 (2018-08-17)

• Configuration writers that write out karma configuration scripts that import other Node.js modules that are present within the environment that the karma binary reside in should no longer encounter a Error: Cannot find module message. [ #10 ]

• Permit the use of other karma_conf dict/mapping types in the spec. [ #9 ]

2.2.1 (2018-08-01)

• Allow the karma configuration writer to be specified in the spec, such that it may be overridden by framework integration packages. [ #8 ]

2.2.0 (2018-07-24)

• Support the correct resolution of test child module registries, which was introduced in calmjs-3.3.0. [ #6 ]

• Ensure that a missing karma binary is also correctly dealt with by the same set of exception and flags. [ #7 ]

2.1.0 (2018-05-28)

• Ensure the exit code indicates failure if the artifact test entry point references an import that cannot be resolved (failure to set up the test must result in a failure). [ #3 ]

• Make use of the corrected semantics provided by calmjs-3.1.0 for the deferred export location verification, which also silences the calmjs-4.0.0 deprecation warning. [ #5 ]

2.0.0 (2018-01-10)

• Migration to the calmjs-3.0.0 API.

• Bumped a number of dependencies on Node.js packages.

• The paths that are covered by the test coverage report are now recorded in the Spec as part of the test execution workflow through the KarmaDriver.

• Provide framework and command for testing of predefined artifacts generated for packages defined through the calmjs.artifacts registry; calmjs.artifacts.tests registry was created such that toolchain packages may declare the test compliment builder functions to facilitate testing for their dependent packages.

• Implemented --cover-report-type flag to support the specification of multiple coverage report types to be generated, and ensured that the defined report types actually work (a karma/istanbul bug was found and a workaround was implemented).

• A number of internal code refactor, i.e. a number of internal API changes have happened.

• Deprecated --coverage-type flag, as it is inconsistently named and that features provided by --cover-report-type superseded this.

• Deprecated --test-package flag in favor of --test-with-package for more clarity about the intention of that flag.

1.1.0 (2017-08-10)

• Tests are now automatically wrapped by a default template when served by karma to better limit the scope of the variables defined within each file. This can be disabled using --no-wrap-tests flag on the karma runtime.

1.0.3 (2017-05-22)

• Move the --artifact and --cover-artifact flag up to the main karma runtime to permit wider and more flexible usage for all runners.

• Correctly report the path of missing specified artifacts in the logs.

1.0.2 (2017-01-27)

• Provide test prefix key and constant.

1.0.1 (2016-11-30)

• Correct the inability to launch standard graphical browsers directly via the runner under Windows.

1.0.0 (2016-11-18)

• Initial release of the development support for the calmjs framework.

• Include karma test runner integration as a calmjs runtime that can accept calmjs toolchain runtimes to facilitate testing.

• Generation of test coverage reports of JavaScript sources executed.

• Leverage the toolchain advice system for adding the test runner and also permit the modification of test configurations by toolchain implementations that require specific instructions for a successful execution of tests.

• Permit integration with other packages for testing artifacts generated by other systems.