summaryrefslogtreecommitdiffstats
path: root/js/src/jsapi-tests/README
blob: 06b3fb2b45c7f0cee47321fb0270d1d80a592957 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
# 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.

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:

    cd $OBJDIR/dist/bin
    ./jsapi-tests

To run the tests in a debugger:

    cd $OBJDIR/dist/bin
    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 UNIFIED_SOURCES list
    in moz.build.


## Writing test code

Here is a sample test:

    #include "tests.h"

    BEGIN_TEST(testIntString_bug515273)
    {
        RootedValue v(cx);

        EVAL("'42';", &v);
        JSString *str = v.toString();
        CHECK(JS_StringHasBeenInterned(cx, str));
        CHECK(JS_FlatStringEqualsAscii(JS_ASSERT_STRING_IS_FLAT(str), "42"));
        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::Evaluate. 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 on failure. See sameValue below.

    CHECK_EQUAL(const T &a, const U &b);

        CHECK(a == b), but with a more detailed error message.

    CHECK_NULL(const T *ptr);

        CHECK(ptr == nullptr), but with a more detailed error message.

        (This is here because CHECK_EQUAL(ptr, nullptr) fails to compile on GCC
        2.5 and before.)


    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();