1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/js/src/jsapi-tests/README Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,158 @@
1.4 +=== JSAPI Test Suite
1.5 +
1.6 +The tests in this directory exercise the JSAPI.
1.7 +
1.8 +
1.9 +--- Building and running the tests
1.10 +
1.11 +If you built JS, you already built the tests.
1.12 +
1.13 +If you did `make check` in your JS objdir, you already ran them.
1.14 +
1.15 +The tests are built by default when you build JS. All the tests are compiled
1.16 +into a single binary named jsapi-tests. They all run in a single process.
1.17 +
1.18 +To run the tests in a debugger:
1.19 +
1.20 + cd $OBJDIR/jsapi-tests
1.21 + gdb ./jsapi-tests
1.22 +
1.23 +
1.24 +--- Creating new tests
1.25 +
1.26 + 1. You can either add to an existing test*.cpp file or make a new one.
1.27 + Copy an existing test and replace the body with your test code.
1.28 + The test harness provides `cx`, `rt`, and `global` for your use.
1.29 +
1.30 + 2. If you made a new .cpp file, add it to the CPPSRCS list in Makefile.in.
1.31 +
1.32 +
1.33 +--- Writing test code
1.34 +
1.35 +Here is a sample test:
1.36 +
1.37 + #include "tests.h"
1.38 +
1.39 + BEGIN_TEST(testIntString_bug515273)
1.40 + {
1.41 + jsval v;
1.42 + EVAL("'42';", &v);
1.43 +
1.44 + JSString *str = JSVAL_TO_STRING(v);
1.45 + const char *bytes = JS_GetStringBytes(str);
1.46 + CHECK(strcmp(bytes, "42") == 0);
1.47 + return true;
1.48 + }
1.49 + END_TEST(testIntString_bug515273)
1.50 +
1.51 +The BEGIN_TEST and END_TEST macros bracket each test. By convention, the test
1.52 +name is <testFilename>_<detail>. (The above test is in testIntString.cpp.)
1.53 +
1.54 +The curly braces are required. This block is the body of a C++ member function
1.55 +that returns bool. The test harness calls this member function
1.56 +automatically. If the function returns true, the test passes. False, it fails.
1.57 +
1.58 +JSAPI tests often need extra global C/C++ code: a JSClass, a getter or setter
1.59 +function, a resolve hook. Put these before the BEGIN_TEST macro.
1.60 +
1.61 +The body of the test can use these member variables and macros, defined in
1.62 +tests.h:
1.63 +
1.64 + JSRuntime *rt;
1.65 + JSContext *cx;
1.66 + JSObject *global;
1.67 +
1.68 + The test framework creates these fresh for each test. The default
1.69 + environment has reasonable default settings, including
1.70 + JSOPTION_VAROBJFIX, JSOPTION_JIT, a global object of a class with
1.71 + JSCLASS_GLOBAL_FLAGS, and an error reporter that prints to stderr.
1.72 + See also "Custom test setup" below.
1.73 +
1.74 + EXEC(const char *code);
1.75 +
1.76 + Execute some JS code in global scope, using JS_EvaluateScript. Return
1.77 + false if that fails. (This means that if the code throws an uncaught JS
1.78 + exception, the test fails.)
1.79 +
1.80 + EVAL(const char *code, jsval *vp);
1.81 +
1.82 + Same as EXEC, but store the result value in *vp.
1.83 +
1.84 + CHECK(bool cond);
1.85 +
1.86 + If the condition is not true, print an error message and return false,
1.87 + failing the test.
1.88 +
1.89 + CHECK_SAME(jsval a, jsval b);
1.90 +
1.91 + If a and b are different values, print an error message and return
1.92 + false, failing the test.
1.93 +
1.94 + This is like CHECK(sameValue(a, b)) but with a more detailed error
1.95 + message. See sameValue below.
1.96 +
1.97 + bool knownFail;
1.98 +
1.99 + Set this to true if your test is known to fail. The test runner will
1.100 + print a TEST-KNOWN-FAIL line rather than a TEST-UNEXPECTED-FAIL
1.101 + line. This way you can check in a test illustrating a bug ahead of the
1.102 + fix.
1.103 +
1.104 + If your test actually crashes the process or triggers an assertion,
1.105 + this of course will not help, so you should add something like
1.106 +
1.107 + knownFail = true; // see bug 123456
1.108 + return false; // the code below crashes!
1.109 +
1.110 + as the first two lines of the test.
1.111 +
1.112 + bool isNegativeZero(jsval v);
1.113 + bool isNaN(jsval v);
1.114 +
1.115 + Self-explanatory.
1.116 +
1.117 + bool sameValue(jsval v1, jsval v2);
1.118 +
1.119 + True if v1 and v2 are the same value according to the ES5 SameValue()
1.120 + function, to wit:
1.121 +
1.122 + SameValue(NaN, NaN) is true.
1.123 + SameValue(-0, 0) is false.
1.124 + Otherwise SameValue(a, b) iff a === b.
1.125 +
1.126 +
1.127 +--- Custom test setup
1.128 +
1.129 +Before executing each test, the test framework calls the tests' init() member
1.130 +function, which populates the rt, cx, and global member variables.
1.131 +
1.132 +A test can customize the test setup process by overloading virtual member
1.133 +functions, like this:
1.134 +
1.135 + const JSClass globalClassWithResolve = { ... };
1.136 +
1.137 + BEGIN_TEST(testGlobalResolveHook)
1.138 + {
1.139 + RootedValue v;
1.140 + EVAL("v", v.address());
1.141 + CHECK_SAME(v, JSVAL_VOID);
1.142 + return true;
1.143 + }
1.144 +
1.145 + // Other class members can go here.
1.146 +
1.147 + // This one overloads a base-class method.
1.148 + virtual JSClass *getGlobalJSClass() {
1.149 + return &globalClassWithResolve;
1.150 + }
1.151 + END_TEST(testGlobalResolveHook)
1.152 +
1.153 +The overloadable member functions are:
1.154 +
1.155 + virtual bool init();
1.156 + virtual void uninit();
1.157 + virtual JSRuntime * createRuntime();
1.158 + virtual JSContext * createContext();
1.159 + virtual JSClass * getGlobalClass();
1.160 + virtual JSObject * createGlobal();
1.161 +
