Debian Codegraph @

js/src/jsapi-tests/README

raw
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