Python envjasmine wrapper
=========================

This is a thin python wrapper around the envjasmine_ JavaScript
testing framework.


.. contents::


Installation
------------

You can install pyenvjasmine using pip_::

  pip install pyenvjasmine

Or you can grab the latest sources using Mercurial_ from https://code.codigo23.net/hg/pyenvjasmine::

  hg clone https://code.codigo23.net/hg/pyenvjasmine

and install it from there::

  python setup.py install

Also, you can use it directly from the sources directory, in *development mode*
(useful if you want to contribute to the project)::

  pip install -e .

.. note::

   More about the *development mode* here:

   https://packaging.python.org/en/latest/distributing.html#working-in-development-mode

.. warning::

   Starting with version **0.3.0**, pyenvjasmine has support to run tests with
   different browsers/engines. The headless browser rhino is included with
   pyenvjasmine, but in order to use the other engines, you have to install the
   needed browser(s).

   Right now, only phantomjs_ is supported, so ensure you have it installed if
   you want to use that browser/engine to run tests on. **Required if you want
   to run tests on jasmine 3.x** (also required to run pyenvjasmine's own
   tests).


Running pyenvjasmine tests
--------------------------

To run the tests on this code here (as opposed to *your* JavaScript code you
want to test), install pyenvjasmine (and phantomjs) and then run::

  py.test


Run your own tests
------------------

The easiest way is to put your "specs" (JavaScript tests) into some directory
in your code, then in your python tests, add a new TestCase with just one test
that runs all your JavaScript tests.

The simplest solution is to set capture_output to False, so you see the output
from the js tests on the console. Something like this::

    import pytest
    from pyenvjasmine.runner import Runner

    class TestJavaScript(object):
        def test_my_javascript(self):
            runner = Runner(
                testdir='/path/to/my/testdir',
                configfile='relative/path/to/configfile',
                testing_environment='phantomjs')
            success, stdout = runner.run()
            # assert on success, will be true if tests passed, False if any
            # test failed
            assert success, "One or more javascript tests have failed"
            # you can inspect stdout if you want to get more info, but it
            # will be printed to the console stdout anyway
            assert b'Total: 120' in stdout

In this example, the *phantomjs* browse/engine is used, replace that with
*rhino* to run tests on rhino + jasmine 1.x.

.. note::

   *phantomjs* is the preferred browser/engine, so it is what pyenvjasmine
   will use as a default if you don't set *testing_environment* when creating
   a new *Runner* instance.


.. _Mercurial: https://www.mercurial-scm.org
.. _envjasmine : https://github.com/trevmex/EnvJasmine
.. _pip: http://www.pip-installer.org/en/latest/index.html
.. _easy_install: http://peak.telecommunity.com/DevCenter/EasyInstall
.. _phantomjs: http://phantomjs.org