summaryrefslogtreecommitdiffstats
path: root/js/src/jsapi-tests/README
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 19:33:14 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 19:33:14 +0000
commit36d22d82aa202bb199967e9512281e9a53db42c9 (patch)
tree105e8c98ddea1c1e4784a60a5a6410fa416be2de /js/src/jsapi-tests/README
parentInitial commit. (diff)
downloadfirefox-esr-36d22d82aa202bb199967e9512281e9a53db42c9.tar.xz
firefox-esr-36d22d82aa202bb199967e9512281e9a53db42c9.zip
Adding upstream version 115.7.0esr.upstream/115.7.0esrupstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'js/src/jsapi-tests/README')
-rw-r--r--js/src/jsapi-tests/README173
1 files changed, 173 insertions, 0 deletions
diff --git a/js/src/jsapi-tests/README b/js/src/jsapi-tests/README
new file mode 100644
index 0000000000..5e03748f0e
--- /dev/null
+++ b/js/src/jsapi-tests/README
@@ -0,0 +1,173 @@
+# 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.
+They must be run from the js/src directory.
+
+To run the tests:
+
+ $OBJDIR/dist/bin/jsapi-tests
+
+To run the tests in a debugger:
+
+ gdb $OBJDIR/dist/bin/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 "jsapi-tests/tests.h"
+
+ BEGIN_TEST(testIntString_bug515273)
+ {
+ RootedValue v(cx);
+
+ EVAL("'42';", &v);
+ JSString *str = v.toString();
+ CHECK(JS_StringHasBeenInterned(cx, str));
+ CHECK(JS_FlatStringEqualsLiteral(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 from the JSAPIRuntimeTest class, 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();
+