XForms Test Suite README -- Developer

What is this?

An introduction to the test suite can be found here. This document describes how test suite functions, the format of the testcase XML file, and how to create new tests for it.

System overview

The system works by transforming a testcase XML into the needed format for a test run (either visual or jsunit):

test.xml -> [testcase.xsl] -> test.xhtml (visual)
                           -> test.xhtml (jsunit)

It also supplies a runtests.php file that sets up a JsUnit testsuite file containing tests from all dirs that have been "JsUnit-enabled".

Testcase XML format

The "skeleton" for a test file looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<testcase title="Test title"
          xmlns:html="http://www.w3.org/1999/xhtml"
          xmlns:ev="http://www.w3.org/2001/xml-events"
          xmlns:xforms="http://www.w3.org/2002/xforms">

<xforms:model id="i_model">
  <xforms:instance xmlns="">
    <data>
    </data>
  </xforms:instance>
</xforms:model>

<head>
  <style xmlns="http://www.w3.org/1999/xhtml" type="text/css">
    @namespace xf url("http://www.w3.org/2002/xforms");
  </style>
</head>

<description>
  <div xmlns="http://www.w3.org/1999/xhtml">
  </div>
</description>

<body>
  <div xmlns="http://www.w3.org/1999/xhtml">
  </div>
</body>

<test>
</test>

</testcase>

That is, there's room for stuff that should go into the head element and for defining models. A description of the test in description, then there is stuff that goes into the body, and then a test section. Except for the last one, the rest should be rather self-explanatory.

Test Functions

The test section in the allows the test writer to write a sequence of tests that will be executed synchroneously and in-order, when the form is ready. The following tests are available. They all take id as the first parameter, which is the id of the control that they should test.

Test	Description
assertValue(id, value)	Assert that the control has the given value. Just does a string compare.
assertNotValue(id, value)	Assert that the control has does not have the given value. Just does a string compare.
assertNotBound(id)	Assert that the control is not bound to an instance data node.
activate(id)	Activates a given control, that is, sends a `DOMActivate` to it. Triggers and such likes to be massaged this way :)
setValue(id, value)	Sets the value of the given control. This is done through the `nsIXFormsAccessors` interface, so it might not produce exactly the same results as if it was entered through the UI.
assertReadonly(id)	Assert that the control is read-only.
assertReadwrite(id)	Assert that the control is read-write.
assertEnabled(id)	Assert that the control is enabled.
assertDisabled(id)	Assert that the control is disabled.
assertRequired(id)	Assert that the control is required.
assertOptional(id)	Assert that the control is optional.
assertValid(id)	Assert that the control is valid.
assertInvalid(id)	Assert that the control is invalid.
assertInRange(id)	Assert that the control is in range.
assertOutOfRange(id)	Assert that the control is out of range.
assertType(id, ns, type)	Assert that the control is of the given type. You need to give the namespace and the name of the type.
evalJS(code)	Evaluates the given javascript code.
assertEvent(id, event)	Assert that the control receives an event. I'm still trying to figure out the right semantics for this. For now I only listen for the events that have been "asserted", and it only looks for the first event received. So if you assert X and Y, and Y is received before X, this fails.
assertNotEvent(id, event)	Assert that an event is not received. Not quite sure about the semantics for this one either...

Example Testcase

Here is a simple testcase that tests the form setup, and whether changing the value in the input changes the value in the output:

<?xml version="1.0" encoding="UTF-8"?>
<testcase title="Test Test Test"
          xmlns:html="http://www.w3.org/1999/xhtml"
          xmlns:xforms="http://www.w3.org/2002/xforms">

<xforms:model id="i_model">
  <xforms:instance xmlns="">
    <data>42</data>
  </xforms:instance>
</xforms:model>

<description>
  <div xmlns="http://www.w3.org/1999/xhtml">
    Test that changing a node value takes place, and also refreshes other
    controls bound to the same node.
  </div>
</description>

<body>
  <div xmlns="http://www.w3.org/1999/xhtml">
    <xforms:input id="inp" ref=".">
      <xforms:label>Yee input: </xforms:label>
    </xforms:input>
    <br/>
    <xforms:output id="out" ref=".">
      <xforms:label>Yee output: </xforms:label>
    </xforms:output>
  </div>
</body>

<test>
  <assertValue control="inp" value="42"/>
  <assertValue control="out" value="42"/>
  <setValue control="inp" value="boo"/>
  <assertValue control="inp" value="boo"/>
  <assertValue control="out" value="boo"/>
</test>

</testcase>

Remarks

Note that all this is under construction, and the JsUnit tests are not functioning as well as the visual ones for now. Remeber to look at the TODO as well.