mozilla

Compare Revisions

Writing xpcshell-based unit tests

Change Revisions

Revision 503249:

Revision 503249 by jduell on

Revision 528989:

Revision 528989 by P.A. on

Title:
Writing xpcshell-based unit tests
Writing xpcshell-based unit tests
Slug:
Mozilla/QA/Writing_xpcshell-based_unit_tests
Mozilla/QA/Writing_xpcshell-based_unit_tests
Tags:
"Developing Mozilla", "Guide", "Automated testing"
"Developing Mozilla", "Guide", "Automated testing"
Content:

Revision 503249
Revision 528989
n62      XPCShell test utility functionsn62      XPCShell test functions
63    </h3>
64    <p>63    </h3>
65      xpcshell tests have access to the following utility functio
>ns. All of them are defined in <a class="external" href="http://m 
>xr.mozilla.org/mozilla-central/source/testing/xpcshell/head.js" t 
>itle="http://mxr.mozilla.org/mozilla-central/source/testing/xpcsh 
>ell/head.js">testing/xpcshell/head.js</a> if you want to see how  
>they work. 
66    </p>64    <p>
65      xpcshell tests have access to the following functions. They
 > are defined in <a class="external" href="http://mxr.mozilla.org/
 >mozilla-central/source/testing/xpcshell/head.js" title="http://mx
 >r.mozilla.org/mozilla-central/source/testing/xpcshell/head.js">te
 >sting/xpcshell/head.js</a> and <a href="/en-US/docs/">testing/mod
 >ules/Assert.jsm</a> if you want to see how they work.
66    </p>
67    <h4>
68      Test case registration and execution
69    </h4>
nn77    </dl>
78    <dl>
79      <dt>
80        <code>run_next_test()</code>
81      </dt>
82      <dd>
83        Run the next test function from the list of asynchronous 
 >tests. Each test function must call <code>run_next_test()</code> 
 >when it's done. <code>run_test()</code> should also call <code>ru
 >n_next_test()</code> to start execution of all asynchronous test 
 >functions.
84      </dd>
85    </dl>
86    <dl>
n78        Add a generator to the list of tests that are to be run an91        Add a generator to the list of tests that are to be run a
>synchronously. Whenever the generator <code>yield</code>s a <a hr>synchronously. Whenever the generator <code>yield</code>s a <a hr
>ef="/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm">Prom>ef="/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm">Prom
>ise</a>, the test runner waits until the promise is resolved or r>ise</a>, the test runner waits until the promise is resolved or r
>ejected before proceeding. As in <a href="/en-US/docs/Mozilla/Jav>ejected before proceeding. As in <a href="/en-US/docs/Mozilla/Jav
>aScript_code_modules/Task.jsm">Task.jsm</a>, rejected promises ar>aScript_code_modules/Task.jsm">Task.jsm</a>, rejected promises ar
>e converted into exceptions, and resolved promises are converted >e converted into exceptions, and resolved promises are converted 
>into values. <code>run_test()</code> should also call <code>run_n>into values. <code>run_test()</code> should also call <code>run_n
>ext_test()</code> to start execution of all asynchronous test fun>ext_test()</code> to start execution of all asynchronous test fun
>ctions.>ctions. The test cases must not call <code>run_next_test()</code>
 >, it is called automatically when the task finishes.
92      </dd>
93      <dt>
94        <code>do_register_cleanup(<var>callback</var>)</code>
95      </dt>
79      </dd>96      <dd>
97        Executes the function <code>callback</code> after the tes
 >t has finished running, regardless of whether the test passes or 
 >fails. You can use this to clean up anything that might otherwise
 > cause problems between test runs.
98      </dd>
99      <dt>
100        <code>do_test_pending()</code>
101      </dt>
102      <dd>
103        Delay exit of the test until do_test_finished() is called
 >. do_test_pending() may be called multiple times, and do_test_fin
 >ished() must be paired with each before the unit test will exit.
104      </dd>
105      <dt>
106        <code>do_test_finished()</code>
107      </dt>
108      <dd>
109        Call this function to inform the test framework that an a
 >synchronous operation has completed. If all asynchronous operatio
 >ns have completed (i.e., every do_test_pending() has been matched
 > with a do_test_finished() in execution), then the unit test will
 > exit.
110      </dd>
111    </dl>
112    <h4>
113      Assertions and logging
114    </h4>
115    <dl>
116      <dt>
117        <code>do_check_eq(<var>a</var>, <var>b</var>)</code>
118      </dt>
119      <dd>
120        Call this function to assert that two objects are equal (
 >using ==). If not equal, an exception is logged and the test case
 > is halted.
121      </dd>
122      <dt>
123        <code>do_check_neq(<var>a</var>, <var>b</var>)</code>
124      </dt>
125      <dd>
126        Call this function to assert that two objects are not equ
 >al (using !=). If equal, an exception is logged and the test case
 > is halted.
127      </dd>
128      <dt>
129        <code>do_check_true(<var>expr</var>)</code>
130      </dt>
131      <dd>
132        Call this function to assert that <code>expr</code> is eq
 >ual to <code>true</code>.
133      </dd>
134      <dt>
135        <code>do_check_false(<var>expr</var>)</code>
136      </dt>
137      <dd>
138        Call this function to assert that <code>expr</code> is eq
 >ual to <code>false</code>.
139      </dd>
140      <dt>
141        <code>do_check_null(<var>expr</var>)</code>
142      </dt>
143      <dd>
144        Call this function to assert that <code>expr</code> is eq
 >ual to <code>null</code>.
145      </dd>
146      <dt>
147        <code>do_print(<var>messageText</var>)</code>
148      </dt>
149      <dd>
150        Call this function to print text to the test's log file.
151      </dd>
152    </dl>
153    <dl>
n90        <code>do_check_eq(<var>a</var>, <var>b</var>)</code>n164        <code>Assert.throws(<em>callback</em><var>, expectedExcep
 >tion</var>)</code>
91      </dt>
92      <dd>
93        Call this function to assert that two objects are equal (
>using ==). If not equal, an exception is logged and the test case 
> is halted. 
94      </dd>
95      <dt>165      </dt>
96        <code>do_check_neq(<var>a</var>, <var>b</var>)</code>
97      </dt>
98      <dd>
99        Call this function to assert that two objects are not equ
>al (using !=). If equal, an exception is logged and the test case 
> is halted. 
100      </dd>166      <dd>
101      <dt>167        Asserts that the provided callback function throws an exc
 >eption. The <code>expectedException</code> argument can be a mess
 >age string, an <code>Error</code> instance, or a regular expressi
 >on matching part of the error message (like in <code>Assert.throw
 >s(() =&gt; a.b, /is not defined/</code>).
102        <code>do_check_true(<var>expr</var>)</code>
103      </dt>
104      <dd>168      </dd>
105        Call this function to assert that <code>expr</code> is eq
>ual to <code>true</code>. 
106      </dd>169    </dl>
170    <h4>
171      Environment
172    </h4>
107      <dt>173    <dl>
108        <code>do_check_false(<var>expr</var>)</code>
109      </dt>
110      <dd>
111        Call this function to assert that <code>expr</code> is eq
>ual to <code>false</code>. 
112      </dd>
113      <dt>
114        <code>do_check_null(<var>expr</var>)</code>
115      </dt>
116      <dd>
117        Call this function to assert that <code>expr</code> is eq
>ual to <code>null</code>. 
118      </dd>
119      <dt>
120        <code>do_print(<var>messageText</var>)</code>
121      </dt>
122      <dd>
123        Call this function to print text to the test's log file.
124      </dd>
125      <dt>
126        <code>do_execute_soon(<var>callback</var>)</code>
127      </dt>
128      <dd>
129        Executes the function <code>callback</code> on a later pa
>ss through the event loop. Use this when you want some code to ex 
>ecute after the current function has finished executing, but you  
>don't care about a specific time delay. This function will automa 
>tically insert a <code>do_test_pending</code> / <code>do_test_fin 
>ished</code> pair for you. 
130      </dd>
nn190        <code>do_get_idle(</code><code>)</code>
191      </dt>
192      <dd>
193        By default XPCShell tests will disable the idle service, 
 >so that idle time will always be reported as 0. Calling this func
 >tion will re-enable the service and return a handle to it; the id
 >le time will then be correctly requested to the underlying OS. Th
 >e idle-daily notification could be fired when requesting idle ser
 >vice. It is suggested to always get the service through this meth
 >od if the test has to use idle.
194      </dd>
195      <dt>
nn213    </dl>
214    <h4>
215      Utility
216    </h4>
217    <dl>
n171        <code>do_get_idle(</code><code>)</code>n225        <code>do_execute_soon(<var>callback</var>)</code>
172      </dt>
173      <dd>
174        By default XPCShell tests will disable the idle service, 
>so that idle time will always be reported as 0. Calling this func 
>tion will re-enable the service and return a handle to it; the id 
>le time will then be correctly requested to the underlying OS. Th 
>e idle-daily notification could be fired when requesting idle ser 
>vice. It is suggested to always get the service through this meth 
>od if the test has to use idle. 
175      </dd>
176      <dt>226      </dt>
177        <code>do_register_cleanup(<var>callback</var>)</code>
178      </dt>
179      <dd>
180        Executes the function <code>callback</code> after the tes
>t has finished running, regardless of whether the test passes or  
>fails. You can use this to clean up anything that might otherwise 
> cause problems between test runs. 
181      </dd>227      <dd>
228        Executes the function <code>callback</code> on a later pa
 >ss through the event loop. Use this when you want some code to ex
 >ecute after the current function has finished executing, but you 
 >don't care about a specific time delay. This function will automa
 >tically insert a <code>do_test_pending</code> / <code>do_test_fin
 >ished</code> pair for you.
229      </dd>
230    </dl>
231    <dl>
t186        Call this function to schedule a timeout. The given functt236        Call this function to schedule a timeout. The given funct
>ion will be called with no arguments provided after the specified>ion will be called with no arguments provided after the specified
> delay (in milliseconds). Note that you must call do_test_pending> delay (in milliseconds). Note that you must call <code>do_test_p
> so that the test isn't completed before your timer fires, and yo>ending</code> so that the test isn't completed before your timer 
>u must call do_test_finished when the actions you perform in the >fires, and you must call <code>do_test_finished</code> when the a
>timeout complete, if you have no other functionality to test. (No>ctions you perform in the timeout complete, if you have no other 
>te: the function argument used to be a string argument to be pass>functionality to test. (Note: the function argument used to be a 
>ed to eval, and some older branches support only a string argumen>string argument to be passed to eval, and some older branches sup
>t or support both string and function.)>port only a string argument or support both string and function.)
187      </dd>
188      <dt>
189        <code>do_test_pending()</code>
190      </dt>
191      <dd>
192        Delay exit of the test until do_test_finished() is called
>. do_test_pending() may be called multiple times, and do_test_fin 
>ished() must be paired with each before the unit test will exit. 
193      </dd>
194      <dt>
195        <code>do_test_finished()</code>
196      </dt>
197      <dd>
198        Call this function to inform the test framework that an a
>synchronous operation has completed. If all asynchronous operatio 
>ns have completed (i.e., every do_test_pending() has been matched 
> with a do_test_finished() in execution), then the unit test will 
> exit. 
199      </dd>
200      <dt>
201        <code>run_next_test()</code>
202      </dt>
203      <dd>
204        Run the next test function from the list of asynchronous 
>tests. Each test function must call <code>run_next_test()</code>  
>when it's done. <code>run_test()</code> should also call <code>ru 
>n_next_test()</code> to start execution of all asynchronous test  
>functions. 

Back to History