This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (pypi.python.org).
Help us improve Python packaging - Donate today!
Project Description

calmjs.dev

Package for aiding the development of JavaScript code to be provided as part of Python packages through integration with Node.js development tools into a Python environment via the Calmjs framework.

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, the support of AMD is implemented through the calmjs.rjs 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

Alternative installation methods (for developers, advanced users)

Development is still ongoing with calmjs.dev, for the latest features and bug fixes, the development version may be desirable; however, the calmjs package must be installed first, otherwise the metadata must be regenerated after the installation, which can be achieved like so:

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

Alternatively, the git repository can be cloned directly and execute python setup.py develop while inside the root of the source directory. Failure to do so will result in failure to install the development packages via calmjs from npm. This failure can be verified by tests for this package failed to correctly execute, and the appearance of distribution option: 'package_json' warning message while installing this package.

As calmjs is declared as both a namespace and a package, mixing installation methods as described above when installing with other calmjs packages may result in the module importer being unable to look up the target files. If such an error does arise please remove all modules and only stick with a single installation method for all packages within the calmjs namespace.

Installation of Node.js external dependencies

As this package integrates a number of Node.js packages to achieve the intended functionality of integration with that environment, Node.js packages required by this package can be installed into the current working directory through the calmjs executable with the included npm command:

$ calmjs npm --install calmjs.dev

Testing the installation

Finally, to verify for the successful installation of calmjs.dev, the included tests may be executed through this command:

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

However, if the steps to install external Node.js dependencies to the current directory was followed, the current directory may be specified as the CALMJS_TEST_ENV environment variable. Under POSIX compatible shells this may be executed instead from within that directory:

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

Do note a number of failures during execution of Karma may appear; this is normal as these are tests that involve the simulation of failures to ensure proper error handling on real test failures.

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 package 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 this 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 and invoke it. Normally, before the bundling is done, the tests will be executed against the transpiled sources in the build directory.

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, if one wishes to run tests a bundle file bundle.js which they assumed to contain code from example.package, they may wish to run tests defined for that package by invoking:

$ calmjs karma run \
    --artifact=bundle.js \
    --test-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-package=example.package \
    --toolchain-package=calmjs.rjs

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.

More on testing in conjunction with artifacts

The --artifact flag can also be specified directly on the karma runner; this has the consequence of enabling the testing of limited or explicitly mapped JavaScript sources exported by specific Python modules. What this means is that instead of building and testing all the dependency modules along with a given module, all those dependencies can be applied to the test environment as a separate, complete artifact. This has the effect of removing the dependency sources from the build directory such that coverage report no longer shows up, with the bonus of also testing the artifact whether or not the it is compatible with the sources being tested. An example with the nunja.stock package which requires nunja:

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

The first command produces the artifact file nunja.js, which is then immediately used by the subsequent command which explicitly filters out all other sources not specified. Otherwise, the standard way is that the dependencies will also be included into the test and the resulting artifact file.

Troubleshooting

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

Error: No provider for “framework:mocha”! (Resolving: framework:mocha)

The most likely cause of this error is that the npm dependencies specified for this package is not available for the current Node.js environment. Please ensure that is installed before trying again. One method is to prepend calmjs.dev to the calmjs npm install command, e.g:

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

Alternatively, package developers can have extras that requires this package, and instruct downstream users interested in the development of that package to install and use the package with that extras flag enabled. For instance, nunja has the support for that:

$ calmjs npm --install nunja[dev]

ERROR [plugin]: “karma-…” plugin: …

A message specific to some plugin may result in the test runner not being able to execute any test. This is typically caused by certain versions of karma test runner not being able to cleanly deal with misbehaving plugins that is available in the node_modules directory. If the plugin shown inside the quote (starting with karma-) is unnecessary for the execution of tests, it should be removed and the test command should be executed again.

UserWarning: Unknown distribution option: ‘package_json’

Installation using the development method will show the above message if calmjs was not already installed into the current environment. Please either reinstall, or regenerate the metadata by running:

$ python setup.py egg_info

In the root of the calmjs.dev source directory to ensure correct behavior of this package.

Changelog

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.
Release History

Release History

1.0.3

This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.0.2

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.0.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.0.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
calmjs.dev-1.0.3-py2.py3-none-any.whl (36.0 kB) Copy SHA256 Checksum SHA256 3.6 Wheel May 22, 2017
calmjs.dev-1.0.3.zip (43.9 kB) Copy SHA256 Checksum SHA256 Source May 22, 2017

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting