b=352305, on behalf of asqueella

r=davel
Mark more clearly the parts of the xpcshell unit test example that
need to be customized, and convert the existing example to an
in-place runnable example

tools/test-harness/xpcshell-simple/Makefile.in

@@ -45,6 +45,12 @@ include $(DEPTH)/config/autoconf.mk
 
 MODULE		= test_harness_xpcshell_simple
 
+# Here's how you let the build system know there are tests in the
+# "example" folder:
+ifdef ENABLE_TESTS
+TOOL_DIRS  += example
+endif
+
 include $(topsrcdir)/config/rules.mk
 
 _TEST_FILES	= test_all.sh

tools/test-harness/xpcshell-simple/example/Makefile.in

@@ -36,6 +36,15 @@
 #
 # ***** END LICENSE BLOCK *****
 
+#
+# Makefile for installing and running xpcshell-based tests. You can use 
+# this file as template when creating tests for a new module. Don't 
+# forget to change the lines marked below. See 
+# http://developer.mozilla.org/en/docs/Writing_xpcshell-based_unit_tests
+# for detailed instructions.
+#
+
+# Note: DEPTH should be set to the relative path to mozilla/
 DEPTH		= ../../../..
 topsrcdir	= @top_srcdir@
 srcdir		= @srcdir@
@@ -43,6 +52,7 @@ VPATH		= @srcdir@
 
 include $(DEPTH)/config/autoconf.mk
 
+# Note: set the test module's name to test_<yourmodule>
 MODULE		= test_harness_xpcshell_simple
 
 include $(topsrcdir)/config/rules.mk
@@ -52,5 +62,6 @@ _UNIT_FILES := $(wildcard $(srcdir)/unit/*.js)
 libs:: $(_UNIT_FILES)
 	$(INSTALL) $^ $(DIST)/bin/$(MODULE)
 
+# Note: Invoke any additional (non-xpcshell) test programs here.
 check::
 	$(RUN_TEST_PROGRAM) $(DIST)/bin/test_all.sh $(DIST)/bin/$(MODULE)

tools/test-harness/xpcshell-simple/example/unit/test_sample.js

@@ -36,10 +36,18 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
-// This is the most basic testcase.  It just sets a timeout, and then exits the
-// test harness when that timeout fires.  This is meant to demonstrate that
-// there is a complete event system available to test scripts.
+/* This is the most basic testcase.  It makes some trivial assertions, 
+ * then sets a timeout, and exits the test harness when that timeout 
+ * fires. This is meant to demonstrate that there is a complete event 
+ * system available to test scripts.
+ * Available functions are described at:
+ * http://developer.mozilla.org/en/docs/Writing_xpcshell-based_unit_tests
+ */
 function run_test() {
+  do_check_eq(57, 57)
+  do_check_neq(1, 2)
+  do_check_true(true);
+
   do_test_pending();
-  do_timeout(1000, "do_test_finished();");
+  do_timeout(100, "do_test_finished();");
 }