doc api tests

chrome/test/data/extensions/api_test/README.txt

Index: chrome/test/data/extensions/api_test/README.txt
diff --git a/chrome/test/data/extensions/api_test/README.txt b/chrome/test/data/extensions/api_test/README.txt
new file mode 100755
index 0000000000000000000000000000000000000000..7e1bc05e47185d68af577b816b6cd9c6ae104809
--- /dev/null
+++ b/chrome/test/data/extensions/api_test/README.txt
@@ -0,0 +1,88 @@
+This directory contains extensions which are unit tests for the extension API.
+These tests are written using the extension API test framework, which allows
+us to do end-to-end testing of extension API in a browser_test.  The general way
+these tests work is to run code in an extension when they're loaded and to post
+a pass or fail notification back up to the C++ unit test which then reports the
+success or failure.  In the common case, the extension runs many subtests and
+then reports up a single pass or fail.  This case is made easy by the test
+framework.
+
+To write a new test:
+
+(1) Add a new browser_test which is a subclass of ExtensionApiTest.  This test
+should call RunExtensionTest("extension_name") to kick off the test.  See
+extension_bookmarks_apitest.cc for an example.
+
+(2) Create an extension of in this directory of the same name as the extension
+that your test referred to ("extension_name" above).  This test should load
+either a background page or a toolstrip which immediately starts its test.
+
+(3) In your extension page, call chrome.test.runTests with an array of
+functions which represent your subtests.  Each of these functions will most
+likely call one or more async extension APIs.  Wrap the callback for each of
+these API calls with chrome.test.callbackPass or chrome.test.callbackFail
+depending on whether or not you're expecting the callback to generate an error
+or not.  That's it.  The test framework notices when each of these callbacks
+is registered and keeps a count of what's expected.  When the right number of
+callbacks has fired, that test function will be marked as passed or failed and
+the next one will be called.  Some other useful helper functions you'll use are
+chrome.test.assertTrue(expr, message), chrome.test.assertEq(left, right) and
+chrome.test.log(message).
+
+Here's an example:
+
+chrome.test.runTests([
+  function getTree() {
+    chrome.bookmarks.getTree(chrome.test.callbackPass(function(results) {
+      chrome.test.assertTrue(compareTrees(results, expected),
+                             "getTree() result != expected");
+    }));
+  },
+
+  function get() {
+    chrome.bookmarks.get("1", chrome.test.callbackPass(function(results) {
+      chrome.test.assertTrue(compareNode(results[0], expected[0].children[0]));
+    }));
+    chrome.bookmarks.get("42", chrome.test.callbackFail(function(){}, "Can't find bookmark for id."));
+  },
+
+  function getArray() {
+    chrome.bookmarks.get(["1", "2"], chrome.test.callbackPass(function(results) {
+      chrome.test.assertTrue(compareNode(results[0], expected[0].children[0]),
+                             "get() result != expected");
+      chrome.test.assertTrue(compareNode(results[1], expected[0].children[1]),
+                             "get() result != expected");
+    }));
+  }
+]);
+
+// compareNode and compareTrees are helper functions that the bookmarks test
+// uses for convenience.  They're not really relevant to the framework itself.
+
+Note that chrome.test.callbackFail takes a second argument which is the error
+message that it expects to get when the callback fails (chrome.extension.lastError.message).
+
+Here's what the output of this test might look like:
+[==========] Running 1 test from 1 test case.
+[----------] Global test environment set-up.
+[----------] 1 test from ExtensionApiTest
+[ RUN      ] ExtensionApiTest.Bookmarks
+( RUN      ) getTree
+(  SUCCESS )
+( RUN      ) get
+(  SUCCESS )
+( RUN      ) getArray
+(  SUCCESS )
+Got EXTENSION_TEST_PASSED notification.
+[       OK ] ExtensionApiTest.DISABLED_Bookmarks (2472 ms)
+[----------] 1 test from ExtensionApiTest (2475 ms total)
+
+[----------] Global test environment tear-down
+[==========] 1 test from 1 test case ran. (2482 ms total)
+[  PASSED  ] 1 test.
+1 test run
+0 test failed
+
+Note the RUN/SUCCESS messages in () - these are the subtests that are run in
+the extension itself.  Anything printed with chrome.test.log() will also display
+in stdout of the browser test (and hence in the buildbot output for that test).