Skip to content

Commit

Permalink
Document how to run tests
Browse files Browse the repository at this point in the history
  • Loading branch information
jcbrand committed Sep 18, 2020
1 parent 5a874a4 commit ced4336
Show file tree
Hide file tree
Showing 2 changed files with 59 additions and 10 deletions.
2 changes: 1 addition & 1 deletion Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -199,7 +199,7 @@ eslint: node_modules
$(ESLINT) spec/ --global converse

.PHONY: check
check: dev eslint
check: eslint | dist/converse.js dist/converse.css
$(KARMA) start karma.conf.js $(ARGS)

.PHONY: test
Expand Down
67 changes: 58 additions & 9 deletions docs/source/testing.rst
Original file line number Diff line number Diff line change
@@ -1,19 +1,68 @@
Automated tests
===============

Converse uses the `Jasmine <https://jasmine.github.io/>`_ testing framework for
writing tests.
Converse uses the `Karma <https://karma-runner.github.io/latest/index.html>`_ test runner and
`Jasmine <https://jasmine.github.io/>`_ testing library for running tests.

Adding tests for your bugfix or feature
----------------------------------------
In addition, we use `ESlint <https://eslint.org/>`_ to run a static analysis (aka
linting) of the source files and report errors.

Take a look at `tests/index.html <https://github.com/jcbrand/converse.js/blob/master/tests/index.html>`_
and the `spec files <https://github.com/jcbrand/converse.js/blob/master/spec/>`_
to see how tests are implemented.
Whenever a commit is pushed to the Converse Github repo, all ESlint checks and
Jasmine tests are run on `Travis CI <https://travis-ci.org/github/conversejs/converse.js>`_.

Running tests
-------------

Check that all tests complete sucessfully.
You can run ESlint by typing ``make eslint``. Similarly the tests can be run via ``make tests``.

Run ``make check`` in your terminal.
To run both eslint and the tests, you can use ``make check``.

When running ``make test`` or ``make check``, a browser will automatically
start up, open a tab at http://localhost:9876 and start running the tests.

You'll see a green bar at the top of the page, and on the right inside it is a ``Debug`` button.

It's often helpful to click that button and run the tests in debug mode. This
way, you see better error output for failed tests.

Automatically run tests on file changes
***************************************

To automatically run the tests whenever you make a change to any of the
Converse source code, you can run ``make watch`` in one terminal, and ``make
tests`` or ``make check`` in another.

``make watch`` will build development bundles of Converse.js (in
``dist/converse.js`` and ``dist/converse.css``) and automatically rebuild them
whenever a source file is modified.

Similarly, Karma will make sure that the tests are re-executed when the
bundle files are rebuilt.


Running individual tests
************************

Converse has over 400 tests, and it can take a few minutes to run through all of them.

When developing on Converse, it's often preferable to have a more rapid
turnaround time between editing a file and checking whether the most relevant
tests have passed.

Jasmine tests are described by `it` functions and the tests names are written to
be read as plain English sentences that start with the word ``it``.

For example:

.. code-block:: javascript
it("is rejected if it's an unencapsulated forwarded message",
Tests are grouped by `describe` functions, and contained in spec files inside
the `spec <https://github.com/jcbrand/converse.js/blob/master/spec/>`_ directory.
To run only a single test, you can replace ``it(`` with ``fit(`` for the particular
test that you want to run. You can also do this for multiple tests. All of them
will be run whenever ``make test`` executes.
To run only a group of tests, you can similarly replace ``describe(`` with ``fdescribe``.

0 comments on commit ced4336

Please sign in to comment.