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

   1 This directory contains extensions which are unit tests for the extension API.
   2 These tests are written using the extension API test framework, which allows
   3 us to do end-to-end testing of extension API in a browser_test.  The general way
   4 these tests work is to run code in an extension when they're loaded and to post
   5 a pass or fail notification back up to the C++ unit test which then reports the
   6 success or failure.  In the common case, the extension runs many subtests and
   7 then reports up a single pass or fail.  This case is made easy by the test
   8 framework.
   9
  10 To write a new test:
  11
  12 (1) Add a new browser_test which is a subclass of ExtensionApiTest.  This test
  13 should call RunExtensionTest("extension_name") to kick off the test.  See
  14 bookmark_extension_apitest.cc for an example.
  15
  16 (2) Create an extension of in this directory of the same name as the extension
  17 that your test referred to ("extension_name" above).  This test should load
  18 a background page which immediately starts its test.
  19
  20 (3) In your extension page, call chrome.test.runTests with an array of
  21 functions which represent your subtests.  Each of these functions will most
  22 likely call one or more async extension APIs.  Wrap the callback for each of
  23 these API calls with chrome.test.callbackPass or chrome.test.callbackFail
  24 depending on whether or not you're expecting the callback to generate an error
  25 or not.  That's it.  The test framework notices when each of these callbacks
  26 is registered and keeps a count of what's expected.  When the right number of
  27 callbacks has fired, that test function will be marked as passed or failed and
  28 the next one will be called.  Some other useful helper functions you'll use are
  29 chrome.test.assertTrue(expr, message), chrome.test.assertEq(left, right) and
  30 chrome.test.log(message).
  31
  32 Here's an example:
  33
  34 chrome.test.runTests([
  35   function getTree() {
  36     chrome.bookmarks.getTree(chrome.test.callbackPass(function(results) {
  37       chrome.test.assertTrue(compareTrees(results, expected),
  38                              "getTree() result != expected");
  39     }));
  40   },
  41
  42   function get() {
  43     chrome.bookmarks.get("1", chrome.test.callbackPass(function(results) {
  44       chrome.test.assertTrue(compareNode(results[0], expected[0].children[0]));
  45     }));
  46     chrome.bookmarks.get("42", chrome.test.callbackFail("Can't find bookmark for id."));
  47   },
  48
  49   function getArray() {
  50     chrome.bookmarks.get(["1", "2"], chrome.test.callbackPass(function(results) {
  51       chrome.test.assertTrue(compareNode(results[0], expected[0].children[0]),
  52                              "get() result != expected");
  53       chrome.test.assertTrue(compareNode(results[1], expected[0].children[1]),
  54                              "get() result != expected");
  55     }));
  56   }
  57 ]);
  58
  59 // compareNode and compareTrees are helper functions that the bookmarks test
  60 // uses for convenience.  They're not really relevant to the framework itself.
  61
  62 Note that chrome.test.callbackFail takes an argument which is the error message
  63 that it expects to get when the callback fails
  64 (chrome.runtime.lastError.message).
  65
  66 Here's what the output of this test might look like:
  67 [==========] Running 1 test from 1 test case.
  68 [----------] Global test environment set-up.
  69 [----------] 1 test from ExtensionApiTest
  70 [ RUN      ] ExtensionApiTest.Bookmarks
  71 ( RUN      ) getTree
  72 (  SUCCESS )
  73 ( RUN      ) get
  74 (  SUCCESS )
  75 ( RUN      ) getArray
  76 (  SUCCESS )
  77 Got EXTENSION_TEST_PASSED notification.
  78 [       OK ] ExtensionApiTest.DISABLED_Bookmarks (2472 ms)
  79 [----------] 1 test from ExtensionApiTest (2475 ms total)
  80
  81 [----------] Global test environment tear-down
  82 [==========] 1 test from 1 test case ran. (2482 ms total)
  83 [  PASSED  ] 1 test.
  84 1 test run
  85 0 test failed
  86
  87 Note the RUN/SUCCESS messages in () - these are the subtests that are run in
  88 the extension itself.  Anything printed with chrome.test.log() will also display
  89 in stdout of the browser test (and hence in the buildbot output for that test).