Metadata-Version: 2.0
Name: calmjs.dev
Version: 1.0.1
Summary: 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.
Home-page: https://github.com/calmjs/calmjs.dev
Author: Tommy Yu
Author-email: tommy.yu@auckland.ac.nz
License: gpl
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Framework :: Setuptools Plugin
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v2 or later (GPLv2+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: JavaScript
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Topic :: Software Development :: Testing
Requires-Dist: calmjs (<3,>=2.0.0)

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`_.

.. image:: https://travis-ci.org/calmjs/calmjs.dev.svg?branch=1.0.x
    :target: https://travis-ci.org/calmjs/calmjs.dev
.. image:: https://ci.appveyor.com/api/projects/status/0mxtiaf2j98w5fy6/branch/1.0.x?svg=true
    :target: https://ci.appveyor.com/project/metatoaster/calmjs-dev/branch/1.0.x
.. image:: https://coveralls.io/repos/github/calmjs/calmjs.dev/badge.svg?branch=1.0.x
    :target: https://coveralls.io/github/calmjs/calmjs.dev?branch=1.0.x


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.

.. |calmjs| replace:: ``calmjs``
.. |calmjs.dev| replace:: ``calmjs.dev``
.. |calmjs.rjs| replace:: ``calmjs.rjs``
.. |npm| replace:: ``npm``
.. |setuptools| replace:: ``setuptools``
.. _Calmjs framework: https://pypi.python.org/pypi/calmjs
.. _calmjs: https://pypi.python.org/pypi/calmjs
.. _calmjs.rjs: https://pypi.python.org/pypi/calmjs.rjs
.. _Node.js: https://nodejs.org
.. _setuptools: https://pypi.python.org/pypi/setuptools


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.

.. |karma| replace:: ``karma``
.. |mocha| replace:: ``mocha``
.. |phantomjs| replace:: ``phantomjs``
.. |sinon| replace:: ``sinon``
.. _karma: https://www.npmjs.com/package/karma
.. _mocha: https://www.npmjs.com/package/mocha
.. _phantomjs: https://www.npmjs.com/package/phantomjs-prebuilt
.. _sinon: https://www.npmjs.com/package/sinon


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.

.. code:: sh

    $ 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:

.. code:: sh

    $ 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:

.. code:: sh

    $ 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:

.. code:: sh

    $ 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:

.. code:: sh

    $ 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:

.. code:: sh

    $ 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:

.. code:: sh

    $ 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:

.. code:: sh

    $ 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:

.. code:: sh

    $ 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.


Troubleshooting
---------------

The following may be some issues that may be encountered with standard
or typical usage of |calmjs.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:

.. code:: sh

    $ python setup.py egg_info

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


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.

Changelog
=========

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.



