Debugging and Testing JavaScript in an HTML5 Application

This tutorial needs a review. You can edit it in GitHub following these contribution guidelines.

HTML5 applications typically combine HTML, CSS and JavaScript to create applications that are run in a browser and that are displayed on a variety of devices, including smartphones, tablets and laptops. This document demonstrates how the IDE provides tools that can help you debug and test JavaScript files in the IDE.

When you want to debug the JavaScript files in your HTML5 application it is recommended that you install the NetBeans Connector extension for the Chrome browser. Debugging is enabled automatically when you run the application in the browser and the extension is installed.

The IDE also enables you to easily configure and run unit tests on JavaScript files using the Jasmine testing framework and the Karma or the JS Test Driver test runners. You can configure the test runner to run unit tests against a variety of browsers and you can quickly specify the JavaScript libraries, scripts and tests that you want the IDE to load when running the tests. When a test fails you can use the debugger to help you locate the problematic code.

For details on how to install the NetBeans Connector extension for the Chrome browser, see the tutorial Getting Started with HTML5 Applications.

For more information on the JavaScript editing features in the IDE, see Creating JavaScript Files in the Developing Applications with NetBeans IDE User's Guide.

To watch a screencast of this tutorial, see Video of Testing and Debugging JavaScript in HTML5 Applications.

To complete this tutorial, you will need the following resources.

Software or Resource Version Required

NetBeans IDE, Java

8.0

Java Development Kit (JDK)

7 or 8

Chrome Browser

 — 

NetBeans Connector Extension for Chrome

1.x

JS Test Driver JAR

 — 

Notes:

  • This document uses JS Test Driver server to run the JavaScript unit tests. You might want to familiarize yourself with the properties of the server at the JS Test Driver project home.

  • This document assumes you have some basic knowledge of, or programming experience with HTML, CSS, and JavaScript.

Creating the HTML5 Sample Application

Perform the following steps to create the HTML5 sample application from a site template.

  1. Choose File > New Project (Ctrl-Shift-N; ⌘-Shift-N on Mac) in the main menu to open the New Project wizard.

  2. Expand the Samples node in the New Project wizard and select the HTML5 category.

  3. Select the AngularJS Phone Catalog Tutorial project. Click Next.

html5 js newproject
Figure 1. AngularJS Phone Catalog Tutorial sample project in New File wizard

  1. Specify a location for the project. Click Finish.

Note. Note that the URL of the template is github. The IDE needs to be able to access the network to retrieve the template archive. Check your proxy settings in the Options window if you encounter problems downloading the archive.

When you click Finish the IDE creates the project and opens the index.html file in the editor. In the Projects window you can see that the project contains index.html and various CSS style sheets and JavaScript files and libraries.

html5 js projectswindow
Figure 2. AngularJS Phone Catalog Tutorial project nodes in Projects window

The project also includes several JavaScript unit test and configuration files that were generated by default.

  1. Confirm that Chrome with NetBeans Connector is selected in the dropdown list in the toolbar.

html5 js selectbrowser
Figure 3. Browser selected in dropdown list in toolbar

  1. Click the Run button in the toolbar (F6) or right-click the project node in the Projects window and choose Run.

When you Run the project the front page of the HTML5 application opens in the Chrome browser and you can see a list of mobile phones. When you click the name of a mobile phone the page displays the phone details.

html5 js runproject1
Figure 4. AngularJS Phone Catalog Tutorial application in the browser window

You will notice that there is a yellow bar in the browser tab that notifies you that the NetBeans Connector is debugging the tab. The IDE and the browser are connected and are able to communicate with each other when the yellow bar is visible. When you launch an HTML5 application from the IDE the JavaScript debugger is automatically enabled. When you save changes to a file or make changes to a CSS style sheet you do not need to reload the page because the browser window is automatically updated to display the changes.

If you close the yellow bar or click Cancel you will break the connection between the IDE and the browser. If you break the connection you will need to run the HTML5 application from the IDE again to use JavaScript debugger.

You will also notice that the NetBeans icon is visible in the URL location field of the browser. You can click the icon to open a menu that provides various options for changing the display size of the browser and for enabling the Inspect in NetBeans mode.

Using the JavaScript Debugger

In this exercise you will place a breakpoint in a JavaScript file and run the application. You can use the tooltip in the editor to quickly see the values of variables.

  1. Expand the js node in the Projects window and double-click controllers.js to open the file in the editor.

  2. Place a line breakpoint on line 16 in controllers.js by clicking in the left margin.

html5 js breakpoint1
Figure 5. Breakpoint set in editor

You can view the breakpoints that are set in the project by choosing Window > Debugging > Breakpoints to open the Breakpoints window.

html5 js breakpoint2
Figure 6. List of breakpoints in Breakpoints window

  1. Click the Run button in the toolbar to run the project again.

When you run the project you will see the same page because the breakpoint that you set was not hit.

  1. In the browser, click one of the entries in the page, for example, Motorola Atrix4G.

You will see that the page is partially loaded but that the data for the phone is missing because the data has not been passed to the JavaScript and rendered.

html5 js break details
Figure 7. Details page of the application is partially loaded in the browser

  1. In the editor in the IDE you can see that the breakpoint was hit and that the Program Counter is currently in line 16 of controllers.js .

  1. Hover your cursor over the phone variable to view a tooltip with information about the variable.

html5 js variables1
Figure 8. Variables tooltip in editor

In the tooltip you can see the following information: phone = (Resource) Resource .

  1. Click the tooltip to expand the tooltip and view a list of the variables and values.

html5 js variables
Figure 9. Expanded variables tooltip in editor

For example, when you expand the android node you can see the values of the strings os and ui .

You can also choose Window > Debugging > Variables to view the list in the Variables window.

  1. Use the step buttons in the toolbar to step through the JavaScript functions in the angular.js library or click the Continue button (F5) to resume the application.

Running JS Unit Tests

You can easily configure the IDE to use the Karma or JS Test Driver test runners to run your unit tests. Karma and JS Test Driver are test runners that provide a URL that is the target for running JavaScript unit tests.

In this tutorial you will use Karma to run the JavaScript unit tests that are included with the sample project. The sample project already includes a Karma configuration file. When you run your tests the test runner server starts and waits to run the tests. Your browser opens and displays a status message in the window that confirms that the server is running and waiting.

How to Run Tests with Karma

To run tests with Karma you first need to download Karma to you local file system. After you install Karma you need to create a Karma configuration file and then specify the location of the installation and configuration file in the Project Properties window.

  1. Install Karma.

You can choose how and where you want to install Karma. You will specify the installation later when you configure the project to use Karma. You can find information about the options for installing Karma on the Karma website.

  1. Create a Karma configuration file.

In this tutorial this step is optional because the sample application already includes a Karma configuration file. You can create a skeleton Karma configuration file by selecting Karma Configuration File in the Unit Tests category of the New File wizard.

karma new config
Figure 10. New Karma Configuration File in the New File wizard

Alternatively, you can run the Karma init command on the command line. See the Karma documentation for more details on using the Karma init command.

  1. Expand the Configuration Files node in the Projects window and double-click karma.conf.js to open the file in the editor. Note that the sample includes two Karma configuration files.

In the Karma configuration file you can see the files that will be included and excluded when you run the tests. You can also see the Karma plugins that are required to run the tests with this configuration.

karma plugins
Figure 11. Karma configuration file in the editor

  1. Right-click the project node in the Projects window and choose Properties in the popup menu.

  1. Select JavaScript Testing category in the Categories pane of the Project Properties window.

  1. Select Karma in the Testing Provider drop-down list. Click OK.

  1. Open the Project Properties window again and select Karma under the JavaScript Testing category in the Categories pane.

  1. Specify the location of your Karma installation.

If you installed Karma in your project directory you can click Search and the IDE will find the installation. You can also click Browse to manually locate your local Karma installation.

  1. Specify the location of your Karma configuration file. Click OK.

In this tutorial you can click Search and the IDE will find the default Karma configuration file. You can also click Browse to manually locate a configuration file.

karma properties window
Figure 12. Karma category in Project Properties window

When you click OK you can see that a Karma node appears under the project node in the Projects window. You right-click the Karma node and start and stop the Karma server and set the configuration file in the popup menu.

  1. Right-click the Karma node in the Projects window and choose Start in the popup menu.

When you click Start the Karma server starts and a browser window opens that displays the status of the server.

karma chrome
Figure 13. Karma server status in the Chrome browser window

In the Output window you can see the status of the server. You are also prompted to install any missing plugins.

karma output1
Figure 14. Configure jsTest Driver node in Services window

Note. The browser window must be open and the Karma server must be running to run the unit tests.

  1. Right-click the Karma node and choose Set Configuration > karma.conf.js to confirm that the correct configuration file is selected. images:./karma-node.png[title="Configure jsTest Driver node in Services window"]

  1. Disable any breakpoints that you set in the project.

You can disable the breakpoints by deselecting the checkbox for the breakpoints in the Breakpoints window.

  1. Right-click the project node in the Projects window and choose Test.

When you choose Test the test runner runs the unit tests on the files. The IDE opens the Test Results window and displays the results of the test.

karma test results
Figure 15. Karma test results

How to Run Test with JS Test Driver

If you want to use JS Test Driver, the IDE provides a configuration dialog for JS Test Driver that you can open from the JS Test Driver node in the Services. The configuration dialog enables you to easily specify the location of the JS Test Driver server JAR and the browsers that you want to run tests against. The JS Test Driver node enables you to quickly see if the server is running and to start and stop the server.

For more details on configuring the JS Test Driver server, see the Getting Started with JsTestDriver documentation.

  1. Download the JS Test Driver JAR and save the JAR to your local system.

  2. In the Services window, right-click the JS Test Driver node and choose Configure.

html5 js testdriver serviceswindow
Figure 16. Configure jsTest Driver node in Services window

  1. In the Configure dialog box, click Browse and locate the JS Test Driver JAR that you downloaded.

  1. Select the Chrome with NetBeans Connector (in NetBeans IDE 7.3, select Chrome with NetBeans JS Debugger) for the browser. Click OK.

html5 js testdriver configure
Figure 17. Configure jsTest Driver dialog box

Notes. You only need to specify the location of the JS Test Driver JAR the first time that you configure the JS Test Driver.

The list of browsers that can be captured and used for testing is based on the browsers that are installed on your system. You can select multiple browsers as slave browsers, but to run the tests a window that can be a slave for the server must be open for each browser. The selected browsers will be captured automatically when you start the server from the IDE.

When you select Chrome with NetBeans Connector you can debug your tests that are run with JS Test Driver.

  1. Right-click the project node in the Projects window and choose New > Other.

  1. Select the jsTestDriver Configuration File in the Unit Tests category. Click Next.

  1. Confirm that jsTestDriver is the File Name.

  1. In the Created File field, confirm that the location for the file is the config folder of the project ( AngularJSPhoneCat/config/jsTestDriver.conf ).

Note. The jsTestDriver.conf configuration file must be in the config folder of the project. If the location for the created file is not the config folder, click Browse and select AngularJSPhoneCat - Configuration Files folder in the dialog box.

  1. Confirm that the checkbox for downloading the Jasmine libraries is selected. Click Finish.

html5 js testdriver configfile
Figure 18. New jsTestDriver Configuration File wizard

*Note.*You need to download the Jasmine libraries to run jsTestDriver. If you are notified that the IDE is unable to download the Jasmine libraries, check the proxy settings of the IDE in the Options window.

When you click Finish the IDE generates a skeleton jsTestDriver.conf configuration file and opens the file in the editor. In the Projects window you can see that the configuration file is created under the Configuration Files node. If you expand the lib folder under the Unit Tests node you can see that the Jasmine libraries were added to the project.

html5 js testdriver projectswindow
Figure 19. Unit Tests folder in the Projects window

In the editor you can see the following contents of the configuration file that are generated by default:

server: http://localhost:42442

load:
  - test/lib/jasmine/jasmine.js
  - test/lib/jasmine-jstd-adapter/JasmineAdapter.js
  - test/unit/*.js

exclude:

The configuration file specifies the default location of the local server that is used to run the tests. The file also lists the files that must be loaded. By default the list includes the Jasmine libraries and any JavaScript files that are in the unit folder. Tests are usually located in the unit folder but you can modify the list to specify the locations of other files that need to be loaded to run the tests. To run the unit tests you also need to add the location of the JavaScript files that you want to test and the Angular JavaScript libraries to the list of files that are loaded.

For this tutorial, if you want to run the tests using JS Test Driver you will want to add the following files (in bold) to the list of files that are loaded.

load:
    - test/lib/jasmine/jasmine.js
    - test/lib/jasmine-jstd-adapter/JasmineAdapter.js
*
    - app/lib/angular/angular.js
    - app/lib/angular/angular-mocks.js
    - app/lib/angular/angular-route.js
    - app/lib/angular/angular-animate.js
    - app/lib/angular/angular-resource.js
    - app/js/*.js
*
    - test/unit/*.js

  1. After you update the configuration file you can right-click the project node in the Projects window and choose Test.

When you click Test the IDE automatically opens the JS Test runner in the Chrome browser and two tabs in the Output window.

html5 js testdriver browserwindow
Figure 20. jsTestDriver running in the browser window

The Chrome browser window displays a message when the jsTestDriver server is running. You can see that the server is running on localhost:42442 . In the js-test-driver Server tab in the Output window you can see the status of the server.

Note that the JsTestDriver is running in a browser tab and that the NetBeans Connector is debugging the tab. You can debug your unit tests if you run tests with JS Test Driver and select Chrome with NetBeans Connector as one of the target browsers.

html5 js testdriver outputstatus
Figure 21. js-test-driver Server tab in the Output window

Note. The browser window must be open and the jsTestDriver server must be running to run the unit tests. You can start the server and open the window by right-clicking the JS Test Driver node in the Services window and choosing Start.

html5 js testdriver outputwindow
Figure 22. Running JS unit tests tab in Output window

  1. Choose Window > Output > Test Results in the main menu to open the Test Results window and see the results of the tests.

html5 js testdriver testresultswindow
Figure 23. Test Results window

You can click the green check icon in the left margin of the window to view the the expanded list of the tests that passed.

Debugging a JS Unit Test with JS Test Driver

This exercise demonstrates how you can use the IDE and JS Test Driver to debug your unit tests.

Note. NetBeans IDE 8.0 does not support debugging tests that are run with the Karma test runner.

  1. Expand the js folder in the Projects window and double-click controllers.js to open the file in the editor.

  2. Modify line 7 in the file to make the following changes (in bold). Save your changes.

function PhoneListCtrl($scope, Phone) {
  $scope.phones = Phone.query();
  $scope.orderProp = '*name*';
}

When you save your changes the page automatically reloads in the browser. You can see that the order of the phones in the list changed.

  1. Confirm that the JS Test Driver server is running and that the status message is visible in the Chrome browser window.

  1. Right-click the project node in the Projects window and choose Test.

html5 js testdriver testresultswindow fail
Figure 24. Failed test in Test Results window

When you run the test you can see that one of the tests failed with the message that the value "name" was encountered instead of the expected value "age".

  1. Open the Running JS unit tests tab in the Output window.

html5 js testdriver outputwindow fail
Figure 25. Failed test in Running JS unit tests tab in Output window

You can see in the message that the orderProp is expected to be age on line 41.

  1. Click the link in the Running JS unit tests tab to navigate to the line in the test that failed. The test file controllersSpec.js opens in the editor at line 41 (in bold)

it('should set the default value of orderProp model', function() {
      *expect(scope.orderProp).toBe('age');*
    });

You can see that the test expected "age" as the value of scopeOrder.prop .

  1. Set a breakpoint at the line where the test failed (line 41).

  1. Right-click the project node in the Projects window and choose Test.

When you run the test again the program counter hits the breakpoint. If you hover your cursor over scopeOrder.prop you can see in the tooltip that the value of the variable is "name" when the breakpoint is hit.

html5 js testdriver evaluate
Figure 26. IDE showing editor, Evaluate Code window and Variables window

Alternatively, you can choose Debug > Evaluate Expression in the main menu to open the Evaluate Code window. If you type the expression scopeOrder.prop in the window and click the Evaluate Code Fragment button (images:./evaluate-button.png[title="Evaluate Expression button"])(Ctrl-Enter) the debugger displays the value of the expression in the Variables window.

  1. Click Continue in the toolbar to finish running the test.

Summary

In this tutorial you learned how the IDE provides tools that can help you debug and run unit tests on JavaScript files. Debugging is automatically enabled for HTML5 applications when you run the application in the Chrome browser and the NetBeans Connector extension is enabled. The IDE also enables you to easily configure and run unit tests on JavaScript files using the Jasmine testing framework and the JS Test Driver server.

Send Feedback on This Tutorial

See Also

For more information about support for HTML5 applications in the IDE on netbeans.org, see the following resources:

For more information about running unit tests using JS Test Driver, refer to the following documentation: