The Tor Browser / file revision

 === JSAPI Test Suite

 The tests in this directory exercise the JSAPI.

 --- Building and running the tests

 If you built JS, you already built the tests.

 If you did `make check` in your JS objdir, you already ran them.

 The tests are built by default when you build JS. All the tests are compiled

 into a single binary named jsapi-tests. They all run in a single process.

 To run the tests in a debugger:

     cd $OBJDIR/jsapi-tests

     gdb ./jsapi-tests

 --- Creating new tests

  1. You can either add to an existing test*.cpp file or make a new one.

     Copy an existing test and replace the body with your test code.

     The test harness provides `cx`, `rt`, and `global` for your use.

  2. If you made a new .cpp file, add it to the CPPSRCS list in Makefile.in.

 --- Writing test code

 Here is a sample test:

     #include "tests.h"

     BEGIN_TEST(testIntString_bug515273)

     {

         jsval v;

         EVAL("'42';", &v);

         JSString *str = JSVAL_TO_STRING(v);

         const char *bytes = JS_GetStringBytes(str);

         CHECK(strcmp(bytes, "42") == 0);

         return true;

     }

     END_TEST(testIntString_bug515273)

 The BEGIN_TEST and END_TEST macros bracket each test. By convention, the test

 name is <testFilename>_<detail>. (The above test is in testIntString.cpp.)

 The curly braces are required. This block is the body of a C++ member function

 that returns bool. The test harness calls this member function

 automatically. If the function returns true, the test passes. False, it fails.

 JSAPI tests often need extra global C/C++ code: a JSClass, a getter or setter

 function, a resolve hook. Put these before the BEGIN_TEST macro.

 The body of the test can use these member variables and macros, defined in

 tests.h:

     JSRuntime *rt;

     JSContext *cx;

     JSObject *global;

         The test framework creates these fresh for each test. The default

         environment has reasonable default settings, including

         JSOPTION_VAROBJFIX, JSOPTION_JIT, a global object of a class with

         JSCLASS_GLOBAL_FLAGS, and an error reporter that prints to stderr.

         See also "Custom test setup" below.

     EXEC(const char *code);

         Execute some JS code in global scope, using JS_EvaluateScript. Return

         false if that fails. (This means that if the code throws an uncaught JS

         exception, the test fails.)

     EVAL(const char *code, jsval *vp);

         Same as EXEC, but store the result value in *vp.

     CHECK(bool cond);

         If the condition is not true, print an error message and return false,

         failing the test.

     CHECK_SAME(jsval a, jsval b);

         If a and b are different values, print an error message and return

         false, failing the test.

         This is like CHECK(sameValue(a, b)) but with a more detailed error

         message. See sameValue below.

     bool knownFail;

         Set this to true if your test is known to fail. The test runner will

         print a TEST-KNOWN-FAIL line rather than a TEST-UNEXPECTED-FAIL

         line. This way you can check in a test illustrating a bug ahead of the

         fix.

         If your test actually crashes the process or triggers an assertion,

         this of course will not help, so you should add something like

             knownFail = true;  // see bug 123456

             return false;  // the code below crashes!

         as the first two lines of the test.

     bool isNegativeZero(jsval v);

     bool isNaN(jsval v);

         Self-explanatory.

     bool sameValue(jsval v1, jsval v2);

         True if v1 and v2 are the same value according to the ES5 SameValue()

         function, to wit:

         SameValue(NaN, NaN) is true.

         SameValue(-0, 0) is false.

         Otherwise SameValue(a, b) iff a === b.

 --- Custom test setup

 Before executing each test, the test framework calls the tests' init() member

 function, which populates the rt, cx, and global member variables.

 A test can customize the test setup process by overloading virtual member

 functions, like this:

     const JSClass globalClassWithResolve = { ... };

     BEGIN_TEST(testGlobalResolveHook)

         {

             RootedValue v;

             EVAL("v", v.address());

             CHECK_SAME(v, JSVAL_VOID);

             return true;

         }

         // Other class members can go here.

         // This one overloads a base-class method.

         virtual JSClass *getGlobalJSClass() {

             return &globalClassWithResolve;

         }

     END_TEST(testGlobalResolveHook)

 The overloadable member functions are:

     virtual bool init();

     virtual void uninit();

     virtual JSRuntime * createRuntime();

     virtual JSContext * createContext();

     virtual JSClass * getGlobalClass();

     virtual JSObject * createGlobal();