View source for Running JavaScript Tests for the Joomla CMS

<noinclude><languages /></noinclude>
<translate>
==Introduction== <!--T:1-->
</translate>

<translate><!--T:2--> Joomla! core currently has some custom written JavaScript libraries used in performing various tasks. This documentation is about the environment setup used in Joomlaǃ 3 for testing those JavaScript libraries and how to write new tests. For running JavaScript Tests for Joomla 4.x, please see [[S:MyLanguage/JavaScript_Tests_for_Joomla4|JavaScript Tests for Joomla 4]].</translate>

<translate><!--T:3--> When you check out the staging branch of [https://github.com/joomla/joomla-cms Joomla] from GitHub.com, you will see a folder named ''tests'' which contains a folder named ''javascript''. This ''javascript'' folder contains the JavaScript tests written to cover the JavaScript libraries. The tests are written using the Jasmine framework. Karma is used as the test runner. The tests are run on a Firefox browser.</translate>

<translate><!--T:4--> Before you can run the tests, install some software on your local workstation. (See the Prerequisites section below.) This document explains how to run and create your own tests from your local workstation.</translate>

<translate>
==Prerequisites== <!--T:5-->
</translate>

<translate><!--T:6--> The testing environment requires that your local machine has ''Node.js'' installed. To install ''Node.js'', go to the [https://nodejs.org/en/ Node.js official web site], download the setup for your operating system and install it using the installation wizard. NPM (Node Package Manager) is used to manage and setup the JavaScript testing environment.</translate>

<translate>
==Install Dependencies (Packages)== <!--T:7-->
</translate>

<translate><!--T:8--> Open a command line and navigate to the directory ''tests/javascript''</translate>

<translate><!--T:9--> Execute the command</translate> ''npm install''
<translate>
<!--T:10-->
This will install all the dependencies to the ''tests/javascript/node_modules'' directory. If a ''node_modules'' folder does not exist, a folder will be created by ''npm''.</translate>

<translate>
==Starting the Karma Server and Running the Tests== <!--T:11-->
</translate>

<translate><!--T:12--> Execute the command</translate> ''npm test''

<translate><!--T:13--> This starts the web server and Firefox will open. Then the tests will run and the detailed results shown in the command line.</translate>

<translate><!--T:14--> The above command executes ''node tests/javascript/node_modules/karma/bin/karma start karma.conf.js'' in the background.</translate>

<translate><!--T:15--> A video demonstration on running the JavaScript tests is available</translate> [https://www.youtube.com/watch?v=Tp_mLqMhRuA <translate><!--T:16--> here</translate>].

<translate>
==The Magic Inside== <!--T:17-->
</translate>

<translate><!--T:18--> The ''karma.conf.js'' file mentioned in the command for starting the Karma server is the configuration file for the Karma server. Shown below is a screenshot of it.</translate>

[[Image:karma-config-js-file-<translate><!--T:19--> en</translate>.jpg|800px|A screenshot of the karma.conf.js Karma configuration file]]

<translate><!--T:20--> Let's have a look at the configurations that make everything run smoothly.</translate>

<translate><!--T:21--> The ''files'' attribute contains a list of files that the Karma server is going to serve. Unless specified here, no tests can access any file. The set of files currently specified here are the third party JavaScript libraries like jQuery and jasmine-jquery, the set of Joomla! custom JavaScript libraries, the set of spec files that contain test cases along with the files that set up the spec executions and the files that contains the HTML fixtures the libraries are tested on and finally some sample images. We have these files specified with the ''included: false'' option because we are using ''require.js'' for that purpose. The only file that will be both '''loaded''' and '''included''' from karma itself will be the ''test-main.js'' file generated from ''require.js''. From there on, ''require.js'' takes care of including the other loaded files.</translate>

<translate><!--T:22--> The ''exclude'' attribute is used since the ''media/system/js'' directory contains both the minified as well as the uncompressed version of the same library. We need to exclude the uncompressed versions from the loaded files list.</translate>

<translate><!--T:23--> The ''preprocessors'' attribute has the externally added ''coverage'' reporter specified in it. The output in the command line is also made verbose by the ''verbose'' reporter.</translate>
<translate>
<!--T:24-->
''Autowatch'' is set to true so that whenever a change to any loaded file is made, the Karma server would detect that and rerun the tests. This makes the life of the tester easy.</translate>

<translate><!--T:25--> The ''browsers'' attribute accepts an array of browsers that we need the tests to be run on and currently has only Firefox set. In order to use any other browser, the relevant browser launcher needs to be installed and you need to have that browser installed on your local machine.</translate>

<translate><!--T:26-->
For example, to use Chrome browser, navigate to the ''tests/javascript/js'' directory from a command line and execute command
''npm install karma-chrome-launcher --save-dev''. Also add Chrome to the browsers list.</translate>
<translate>
<!--T:27-->
The ''singleRun'' attribute when set to ''true'', automatically stops the Karma server once the tests finish running. That obviously would not be what we expect when we have ''autowatch'' also set to true. Therefore for the ease of development, the option is set to ''false''. Still it is possible to run the server in the 'single run' fashion by passing ''--single-run'' option in the Karma start command.</translate>
''karma start karma.conf.js --single-run''

<translate><!--T:28--> The next file we need to look at is ''test-main.js'' that is an auto-generated file from ''require.js''. We use ''require.js'' to make dynamic loading of dependencies in test specs possible.</translate>

<translate><!--T:29--> Two important changes are done to the auto-generated file.</translate>
<translate><!--T:30--> # The ''paths'' attribute is set in the require configuration. These paths allow us to have aliases assigned to specific JavaScript files. This way for example, whenever we need to add ''tests/javascript/node_modules/jquery/dist/jquery.min.js'' as a dependency, all we need to do is to specify the alias ''jquery'' in the dependency list.</translate>
<translate><!--T:31--> # The next change made to the auto-generated file is the ''shim'' attribute. This is a very simple option where we get to specify the dependencies among the paths set above. For example: ''shim: {jasmineJquery: ['jquery']}'' tells ''require.js'' to load jquery before loading jasmineJquery.</translate>

<translate>
==Writing New Tests== <!--T:32-->
</translate>

<translate><!--T:33--> Test cases are stored in a modular fashion inside the ''tests/javascript/'' directory where we have a directory allocated for a specific JavaScript library. Inside that directory are two JavaScript files, one containing the test cases (''spec.js'') and one containing any setup code necessary to run the tests (''spec-setup.js''). The HTML content that needs to be loaded to the DOM for the tests to run are kept inside a directory named ''fixtures'' and inside it is the ''fixture.html'' file. The ''fixture.html'' file contains pure HTML.</translate>

<translate><!--T:34--> The ''spec-setup.js'' appends the required HTML fixtures to the DOM. The test setup uses a Plugin called ''RequireJSText'' that allows dynamic loading of HTML files possible. The only difference is that the dependency is prefixed with ''text!''. For example, to load the fixture with an alias ''fixtureHtml'', the dependency specified should be ''text!fixtureHtml''.</translate>

<translate><!--T:35--> The tests written so far extensively uses the library ''jasmine-jquery'' that is like an extension of the jQuery functions specifically designed for use with Jasmine.</translate>

<translate>
==Travis Integration== <!--T:36-->
</translate>

<translate><!--T:37--> The Travis integration is made simply by modifying the ''.travis.yml'' file to install the necessary dependencies of the project and finally call ''tests/javascript/node_modules/karma/bin/karma start karma.conf.js --single-run''.</translate>

<translate>
==Code Templates== <!--T:38-->
</translate>

'''spec.js'''
<syntaxhighlight lang="javascript">
/**
 * @copyright   Copyright (C) 2005 - 2016 Open Source Matters, Inc. All rights reserved.
 * @license     GNU General Public License version 2 or later; see LICENSE.txt
 * @package     Joomla
 * @subpackage  JavaScript Tests
 * @since       __DEPLOY_VERSION__
 * @version     1.0.0
 */

define(['jquery', 'testsRoot/{LIBRARY}/spec-setup', 'jasmineJquery', {DEPENDENCIES}], function ($) {
    describe({LIBRARY_NAME}, function () {
        it('should perform expected task', function () {
            expect({SOME_VALUE}).toEqual({SOME_VALUE});
        });
    });
});
</syntaxhighlight>

'''spec-setup.js'''

<syntaxhighlight lang="javascript">
/**
 * @copyright   Copyright (C) 2005 - 2016 Open Source Matters, Inc. All rights reserved.
 * @license     GNU General Public License version 2 or later; see LICENSE.txt
 * @package     Joomla
 * @subpackage  JavaScript Tests
 * @since       __DEPLOY_VERSION__
 * @version     1.0.0
 */

define(['jquery', 'text!testsRoot/{LIBRARY}/fixtures/fixture.html', 'libs/{LIBRARY}', 'jasmineJquery', {DEPENDENCIES}], function ($, fixture) {
    $('body').append(fixture);

    //Any further setup code needed
});
</syntaxhighlight>
'''fixtures/fixture.html'''

<syntaxhighlight lang="html4strict">
<div id="{LIBRARY}js">
    <div id={TEST_CASE_REFERENCE}>
        {HTML_CONTENT}
    </div>
</div>
</syntaxhighlight>

<noinclude>
[[Category:Development{{#translation:}}]]
[[Category:Tutorials{{#translation:}}]]
[[Category:JavaScript{{#translation:}}]]
</noinclude>