Bug 1571938 [wpt PR 18303] - [docs] Document and test testharness.js utility fn, a=testonly
authorMike Pennisi <mike@mikepennisi.com>
Wed, 14 Aug 2019 10:56:33 +0000
changeset 488113 afb522e14cdc327f605c3c465c5e58fbcfd5c977
parent 488112 565b9d7d08dd8a87c37219405e433d2466a45a38
child 488114 32daa44117d0be2030a8ac6bae0e6893da18963d
push id36435
push usercbrindusan@mozilla.com
push dateThu, 15 Aug 2019 09:46:49 +0000
treeherdermozilla-central@0db07ff50ab5 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewerstestonly
bugs1571938, 18303
milestone70.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1571938 [wpt PR 18303] - [docs] Document and test testharness.js utility fn, a=testonly Automatic update from web-platform-tests [docs] Document and test testharness.js utility fn -- wpt-commits: 35a5c1fad24d4a40d21cc4639f542fdd5b37e558 wpt-pr: 18303
testing/web-platform/tests/docs/writing-tests/testharness-api.md
testing/web-platform/tests/resources/test/tests/unit/format-value.html
--- a/testing/web-platform/tests/docs/writing-tests/testharness-api.md
+++ b/testing/web-platform/tests/docs/writing-tests/testharness-api.md
@@ -797,14 +797,32 @@ an event does not fire.
 ### `assert_any(assert_func, actual, expected_array, extra_arg_1, ... extra_arg_N)`
 asserts that one `assert_func(actual, expected_array_N, extra_arg1, ..., extra_arg_N)`
   is true for some `expected_array_N` in `expected_array`. This only works for `assert_func`
   with signature `assert_func(actual, expected, args_1, ..., args_N)`. Note that tests
   with multiple allowed pass conditions are bad practice unless the spec specifically
   allows multiple behaviours. Test authors should not use this method simply to hide
   UA bugs.
 
+## Formatting ##
+
+When many JavaScript Object values are coerced to a String, the resulting value
+will be `"[object Object]"`. This obscures helpful information, making the
+coerced value unsuitable for use in assertion messages, test names, and
+debugging statements.
+
+testharness.js provides a global function named `format_value` which produces
+more distinctive string representations of many kinds of objects, including
+arrays and the more important DOM Node types. It also translates String values
+containing control characters to include human-readable representations.
+
+```js
+format_value(document); // "Document node with 2 children"
+format_value("foo\uffffbar"); // "\"foo\\uffffbar\""
+format_value([-0, Infinity]); // "[-0, Infinity]"
+```
+
 ## Metadata ##
 
 It is possible to add optional metadata to tests; this can be done in
 one of two ways; either by adding `<meta>` elements to the head of the
 document containing the tests, or by adding the metadata to individual
 `[async_]test` calls, as properties.
new file mode 100644
--- /dev/null
+++ b/testing/web-platform/tests/resources/test/tests/unit/format-value.html
@@ -0,0 +1,123 @@
+<!DOCTYPE HTML>
+<html>
+<head>
+  <title>format_value utility function</title>
+  <meta charset="utf-8">
+</head>
+<body>
+<div id="log"></div>
+<script src="/resources/testharness.js"></script>
+<script src="/resources/testharnessreport.js"></script>
+<script>
+"use strict";
+
+test(function() {
+  assert_equals(format_value(null), "null");
+}, "null");
+
+test(function() {
+  assert_equals(format_value(undefined), "undefined");
+}, "undefined");
+
+test(function() {
+  assert_equals(format_value(true), "true");
+  assert_equals(format_value(false), "false");
+}, "boolean values");
+
+test(function() {
+  assert_equals(format_value(0.4), "0.4");
+  assert_equals(format_value(0), "0");
+  assert_equals(format_value(-0), "-0");
+}, "number values");
+
+test(function() {
+  assert_equals(format_value("a string"), "\"a string\"");
+  assert_equals(format_value("new\nline"), "\"new\\nline\"");
+}, "string values");
+
+test(function() {
+  var node = document.createElement("span");
+  node.setAttribute("data-foo", "bar");
+  assert_true(
+    /<span\b/i.test(format_value(node)), "element includes tag name"
+  );
+  assert_true(
+    /data-foo=["']?bar["']?/i.test(format_value(node)),
+    "element includes attributes"
+  );
+}, "node value: element node");
+
+test(function() {
+  var text = document.createTextNode("wpt");
+  assert_equals(format_value(text), "Text node \"wpt\"");
+}, "node value: text node");
+
+test(function() {
+  var node = document.createProcessingInstruction("wpt1", "wpt2");
+  assert_equals(
+    format_value(node),
+    "ProcessingInstruction node with target \"wpt1\" and data \"wpt2\""
+  );
+}, "node value: ProcessingInstruction node");
+
+test(function() {
+  var node = document.createComment("wpt");
+  assert_equals(format_value(node), "Comment node <!--wpt-->");
+}, "node value: comment node");
+
+test(function() {
+  var node = document.implementation.createDocument(
+    "application/xhtml+xml", "", null
+  );
+
+  assert_equals(format_value(node), "Document node with 0 children");
+
+  node.appendChild(document.createElement('html'));
+
+  assert_equals(format_value(node), "Document node with 1 child");
+}, "node value: document node");
+
+test(function() {
+  var node = document.implementation.createDocumentType("foo", "baz", "baz");
+
+  assert_equals(format_value(node), "DocumentType node");
+}, "node value: DocumentType node");
+
+test(function() {
+  var node = document.createDocumentFragment();
+
+  assert_equals(format_value(node), "DocumentFragment node with 0 children");
+
+  node.appendChild(document.createElement("span"));
+
+  assert_equals(format_value(node), "DocumentFragment node with 1 child");
+
+  node.appendChild(document.createElement("span"));
+
+  assert_equals(format_value(node), "DocumentFragment node with 2 children");
+}, "node value: DocumentFragment node");
+
+test(function() {
+  assert_equals(format_value(Symbol("wpt")), "symbol \"Symbol(wpt)\"");
+}, "symbol value");
+
+test(function() {
+ assert_equals(format_value([]), "[]");
+ assert_equals(format_value(["one"]), "[\"one\"]");
+ assert_equals(format_value(["one", "two"]), "[\"one\", \"two\"]");
+}, "array values");
+
+test(function() {
+  var obj = {
+    toString: function() {
+      throw "wpt";
+    }
+  };
+
+  assert_equals(
+    format_value(obj), "[stringifying object threw wpt with type string]"
+  );
+}, "object value with faulty `toString`");
+</script>
+</body>
+</html>