2. Writing tests

Creating test file for page under test

By default TestRunnerJS uses convention method for loading tests for page under test.
For example:
Page under test has following url: http://sc_instance/sitecore/client/Applications/SampleApp/FirstPage
Test folder is located by following path: sc_website/sitecore/shell/client/Tests
By convention TestRunnerJS will load following test file: sc_website/sitecore/shell/client/Tests/SampleApp/FirstPage.js

Sometimes it is necessary to have more than one test file for page under test. In this case it is possible to override default convention. To do this just add sc_testfixture=<testfilename> query parameter to page url.
For example:
Page under test has following url: http://sc_instance/sitecore/client/Applications/SampleApp/FirstPage/Pages/SecondPage
Test folder is located by following path: sc_website/sitecore/shell/client/Tests
Query parameter sc_testfixture has additionalTests value
TestRunnerJS will load following test file: sc_website/sitecore/shell/client/Tests/SampleApp/FirstPage/Pages/additionalTests.js

Writing first test

Test fixture represents RequireJS module. This module returns boolean value. If module returns undefined or false TesrtRunnerJS will nor run tests from this fixture. It is possible to reference another modules from test fixture. The most used module is sitecore. This module contains all SPEAK related controls and functionality. So the simplest testfixture with one test will have the following form:

// Define requirejs module for test fixture and inject sitecore dependency 
define(['sitecore'], function (_sc) {        
  // Define tests using mocha, sinon and chai
  describe('Another page', function () {
    it('Should load text from one TextBox to another on click', function () {
      // arrange
      var expectedText = "Load into Result";
      // Set expected text into action text box
      _sc.app.ActionTextBox.set("text", expectedText);
    
      // act
      // Click ActionButton
      _sc.app.ActionButton.trigger("click");

      // assert
      // Ensure that ResultTextBox contains expected value
      expect(_sc.app.ResultTextBox.get("text")).to.equal(expectedText);
    });
  });

  // Return true to enable test running for this fixture, 
  // false or undefined will turn this test fixture off
  return true;
});

Using fake server

The second useful RequireJS module is fakeServer. This module is based on sinon fake server and allows to separate server side from the client and test client separately. fakeServer module is configured to pass all SPEAK rendering requests to the server, get real renderings markup and do not pass all AJAX data requests and return fake test data instead of this. In order to fake data on page load fake response should be placed in test fixture global scope. For faking test specific responses fake configuration could be placed inside arrange part of the test. Both variants are represented on the following example:

// Define requirejs module for test fixture and inject sitecore 
// and fakeServer dependency
// Fake server will override all data requests to the server
define(['fakeServer', 'sitecore'], function (server, _sc) {
  // Setup fake server response to load items into the list control 
  // during page init in test fixture global scope.
  server.respondWith(
    // Request type
    "POST",
    // Request URL
    "/test/SampleResponse/GetItems",
    // Response code, HTTP headers and content
    [200, { "Content-Type": "application/json" }, JSON.stringify(
      // Content contains JSON with 3 items
      [
        {
          "Name": "Test item 1",
          "Value": "Test value 1"
        }, {
          "Name": "Test item 2",
          "Value": "Test value 2"
        }, {
          "Name": "Test item 3",
          "Value": "Test value 3"
        }]
    )]);
  
  // Define tests using mocha, sinon and chai
  describe('Second page', function () {
    it('Should show message from server on item selection', function (done) {
      // arrange
      var expectedResponse = "Test item 3 was processed on fake server";
      // Setup fake server to respond on request dureng intem selection 
      // on list control
      server.respondWith(
        // Request type
        "GET",
        // Request URL
        "/test/SampleResponse/ProcessSelectedItem?selectedItem=Test item 3",
        // Response code, HTTP header and content
        [200, { "Content-Type": "application/text" }, expectedResponse]
      );
  
      // Get third row on list control
      var thirdRow = $("td[title='Test item 3']");
  
      // act
      // Click on third row
      thirdRow.click();
 
      // assert
      // Asynchronously check text value on ValueLabel text change 
      // Use mocha.check and pass assertion anonymous function 
      // and done callback
      _sc.app.ValueLabel.once("change:text", mocha.check(function () {
        var text = _sc.app.ValueLabel.get("text");
        expect(text).to.equal(expectedResponse);
      }), done);
    });
  });
 
  // Return true to enable test running for this fixture, 
  // false or undefined will turn this test fixture off
  return true;
});

Asynchronous tests

[Introduced in 0.7.1]
It may happen that you need to ensure your expectations asynchronously, especially when waiting for response either from fake server or real one. In this case mocha.check helper function is useful in order to avoid issue with chaii assertions and wrong context.

describe('My page', function () {
  it('Async test', function (done) {
    // arrange
    // Do some arrange

    // act
    // Perform some action

    // assert
    // Asynchronously check assertions 
    // Use mocha.check and pass assertion anonymous function 
    // and done callback
    _sc.app.ValueLabel.once("change:text", mocha.check(function () {
      // Add assertions here
    }), done);
  });
});