README (5176B)
1 # JSAPI Test Suite 2 3 The tests in this directory exercise the JSAPI. 4 5 6 ## Building and running the tests 7 8 If you built JS, you already built the tests. 9 10 The tests are built by default when you build JS. All the tests are compiled 11 into a single binary named jsapi-tests. They all run in a single process. 12 They must be run from the js/src directory. 13 14 To run the tests: 15 16 $OBJDIR/dist/bin/jsapi-tests 17 18 To run the tests in a debugger: 19 20 gdb $OBJDIR/dist/bin/jsapi-tests 21 22 23 ## Creating new tests 24 25 1. You can either add to an existing test*.cpp file or make a new one. 26 Copy an existing test and replace the body with your test code. 27 The test harness provides `cx`, `rt`, and `global` for your use. 28 29 2. If you made a new .cpp file, add it to the UNIFIED_SOURCES list 30 in moz.build. 31 32 33 ## Writing test code 34 35 Here is a sample test: 36 37 #include "jsapi-tests/tests.h" 38 39 BEGIN_TEST(testIntString_bug515273) 40 { 41 RootedValue v(cx); 42 43 EVAL("'42';", &v); 44 JSString *str = v.toString(); 45 CHECK(JS_StringHasBeenInterned(cx, str)); 46 CHECK(JS_FlatStringEqualsLiteral(JS_ASSERT_STRING_IS_FLAT(str), "42")); 47 return true; 48 } 49 END_TEST(testIntString_bug515273) 50 51 The BEGIN_TEST and END_TEST macros bracket each test. By convention, the test 52 name is <testFilename>_<detail>. (The above test is in testIntString.cpp.) 53 54 The curly braces are required. This block is the body of a C++ member function 55 that returns bool. The test harness calls this member function 56 automatically. If the function returns true, the test passes. False, it fails. 57 58 JSAPI tests often need extra global C/C++ code: a JSClass, a getter or setter 59 function, a resolve hook. Put these before the BEGIN_TEST macro. 60 61 The body of the test can use these member variables and macros, defined in 62 tests.h: 63 64 JSRuntime *rt; 65 JSContext *cx; 66 JSObject *global; 67 68 The test framework creates these fresh for each test. The default 69 environment has reasonable default settings, including 70 JSOPTION_VAROBJFIX, JSOPTION_JIT, a global object of a class with 71 JSCLASS_GLOBAL_FLAGS, and an error reporter that prints to stderr. 72 See also "Custom test setup" below. 73 74 EXEC(const char *code); 75 76 Execute some JS code in global scope, using JS::Evaluate. Return 77 false if that fails. (This means that if the code throws an uncaught JS 78 exception, the test fails.) 79 80 EVAL(const char *code, jsval *vp); 81 82 Same as EXEC, but store the result value in *vp. 83 84 CHECK(bool cond); 85 86 If the condition is not true, print an error message and return false, 87 failing the test. 88 89 CHECK_SAME(jsval a, jsval b); 90 91 If a and b are different values, print an error message and return 92 false, failing the test. 93 94 This is like CHECK(sameValue(a, b)) but with a more detailed error 95 message on failure. See sameValue below. 96 97 CHECK_EQUAL(const T &a, const U &b); 98 99 CHECK(a == b), but with a more detailed error message. 100 101 CHECK_NULL(const T *ptr); 102 103 CHECK(ptr == nullptr), but with a more detailed error message. 104 105 (This is here because CHECK_EQUAL(ptr, nullptr) fails to compile on GCC 106 2.5 and before.) 107 108 109 bool knownFail; 110 111 Set this to true if your test is known to fail. The test runner will 112 print a TEST-KNOWN-FAIL line rather than a TEST-UNEXPECTED-FAIL 113 line. This way you can check in a test illustrating a bug ahead of the 114 fix. 115 116 If your test actually crashes the process or triggers an assertion, 117 this of course will not help, so you should add something like 118 119 knownFail = true; // see bug 123456 120 return false; // the code below crashes! 121 122 as the first two lines of the test. 123 124 bool isNegativeZero(jsval v); 125 bool isNaN(jsval v); 126 127 Self-explanatory. 128 129 bool sameValue(jsval v1, jsval v2); 130 131 True if v1 and v2 are the same value according to the ES5 SameValue() 132 function, to wit: 133 134 SameValue(NaN, NaN) is true. 135 SameValue(-0, 0) is false. 136 Otherwise SameValue(a, b) iff a === b. 137 138 139 ## Custom test setup 140 141 Before executing each test, the test framework calls the tests' init() member 142 function, which populates the rt, cx, and global member variables. 143 144 A test can customize the test setup process by overloading virtual member 145 functions from the JSAPIRuntimeTest class, like this: 146 147 const JSClass globalClassWithResolve = { ... }; 148 149 BEGIN_TEST(testGlobalResolveHook) 150 { 151 RootedValue v; 152 EVAL("v", v.address()); 153 CHECK_SAME(v, JSVAL_VOID); 154 return true; 155 } 156 157 // Other class members can go here. 158 159 // This one overloads a base-class method. 160 virtual JSClass *getGlobalJSClass() { 161 return &globalClassWithResolve; 162 } 163 END_TEST(testGlobalResolveHook) 164 165 The overloadable member functions are: 166 167 virtual bool init(); 168 virtual void uninit(); 169 virtual JSRuntime * createRuntime(); 170 virtual JSContext * createContext(); 171 virtual JSClass * getGlobalClass(); 172 virtual JSObject * createGlobal(); 173