Chrome Extensions chrome.experimental.offscreenTabs.* API implementation, docs, and test.

chrome/test/data/extensions/api_test/offscreen_tabs/test.js

Index: chrome/test/data/extensions/api_test/offscreen_tabs/test.js
===================================================================
--- chrome/test/data/extensions/api_test/offscreen_tabs/test.js	(revision 0)
+++ chrome/test/data/extensions/api_test/offscreen_tabs/test.js	(revision 0)
@@ -0,0 +1,371 @@
+// Copyright (c) 2011 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+// OffscreenTabs API test
+// browser_tests.exe --gtest_filter=ExtensionApiTest.OffscreenTabs

[jstritar, 2011/09/16 16:03:50]

ExperimentalApiTest

[alexbost, 2011/09/16 20:18:14]

Done.

+
+var pass = chrome.test.callbackPass;
+var fail = chrome.test.callbackFail;
+var assertEq = chrome.test.assertEq;
+var assertTrue = chrome.test.assertTrue;
+
+var extensionPath =
+  location.href.substring(0, location.href.lastIndexOf("/") + 1);
+
+var inTabs = [
+  { "url":extensionPath + "a.html",
+    "width":200,
+    "height":200
+  },

[jstritar, 2011/09/16 16:03:50]

style nits: spaces after the ':'

{
  "url": extensionPath + "a.html",
  "width": 200,
  "height": 200
},
...

same for the other places.

[alexbost, 2011/09/16 20:18:14]

Done.

+  { "url":extensionPath + "b.html",
+    "width":200,
+    "height":200
+  },
+  { "url":extensionPath + "c.html",
+    "width":1000,
+    "height":800
+  }
+];
+
+// Tab management

[jstritar, 2011/09/16 16:03:50]

can you make the comment more useful? or remove it?

[alexbost, 2011/09/16 20:18:14]

Done.

+var tabs = [];
+
+// Mouse
+

[jstritar, 2011/09/16 16:03:50]

remove new line

[alexbost, 2011/09/16 20:18:14]

Done.

+var tabMouse = new Object();
+
+var mouseEvent = {
+  "button":0,

[jstritar, 2011/09/16 16:03:50]

"button": 0, etc..

[alexbost, 2011/09/16 20:18:14]

Done.

+  "altKey":false,
+  "ctrlKey":false,
+  "shiftKey":false
+};
+
+var x = 11;
+var y = 11;
+
+// Keyboard
+

[jstritar, 2011/09/16 16:03:50]

ditto on these comments. they don't add much right now.

[alexbost, 2011/09/16 20:18:14]

Done.

+var tabKeyboard = new Object();
+
+// ToDataUrl
+
+var tabsCaptured = [];
+
+var nTabsCaptured = 2;
+
+// Util
+
+function compareTabs(tabA, tabB) {
+  assertEq(tabA.id, tabB.id);
+  assertEq(tabA.url, tabB.url);
+  assertEq(tabA.width, tabB.width);
+  assertEq(tabA.height, tabB.height);
+}
+
+function sortTab(tabA, tabB) {
+  return tabA.id - tabB.id;
+}
+
+function verifyTabDoesNotExist(tabId) {
+  chrome.experimental.offscreenTabs.
+      get(tabId, fail("No offscreen tab with id: " + tabId + "."));
+}
+
+// Tab management --------------------------------------------------------------
+
+function startTabManagement() {
+  var nCallbacksNotDone = inTabs.length;
+
+  for (var i=0; i<inTabs.length; i++) {
+    chrome.experimental.offscreenTabs.create(
+        { "url":inTabs[i].url,
+          "width":inTabs[i].width,
+          "height":inTabs[i].height
+        },
+        function() {
+            var j = i;

[jstritar, 2011/09/16 16:03:50]

indent the function body 2 spaces less

[alexbost, 2011/09/16 20:18:14]

Done.

+            return function(tab) {
+              tabs[j] = tab;
+
+              nCallbacksNotDone--;
+
+              if (nCallbacksNotDone == 0)
+                 getAll();
+            }
+          }()
+      );
+  }
+}
+
+function getAll() {
+  chrome.experimental.offscreenTabs.getAll(function(tabsResult) {
+      assertEq(tabs.length, tabsResult.length);

[jstritar, 2011/09/16 16:03:50]

indent 2 spaces less

[alexbost, 2011/09/16 20:18:14]

Done.

+
+      tabs.sort(sortTab);
+      tabsResult.sort(sortTab);
+
+      for (var i=0; i<tabs.length; i++)
+        compareTabs(tabs[i], tabsResult[i]);
+
+      get();
+    });
+}
+
+function get() {
+  var comparedTab = tabs[0];
+
+  chrome.experimental.offscreenTabs.get(comparedTab.id, function(tab) {
+      compareTabs(comparedTab, tab);
+
+      update();
+    });
+}
+
+function update() {
+  var replicatedTab = tabs[0];
+
+  chrome.experimental.offscreenTabs.update(tabs[1].id,
+      { "url":replicatedTab.url,
+        "width":replicatedTab.width,
+        "height":replicatedTab.height
+      },
+      function(tab) {
+          assertEq(replicatedTab.url, tab.url);
+          assertEq(replicatedTab.width, tab.width);
+          assertEq(replicatedTab.height, tab.height);
+
+          remove();
+        }
+    );
+}
+
+function remove() {
+  for (var i=0; i<inTabs.length; i++) {
+    chrome.experimental.offscreenTabs.remove(tabs[i].id);
+
+    verifyTabDoesNotExist(tabs[i].id);
+  }
+}
+
+// Mouse -----------------------------------------------------------------------
+
+function startMouseEvents() {
+  chrome.experimental.offscreenTabs.onUpdated.addListener(listener =

[jstritar, 2011/09/16 16:03:50]

We have a helper method, chrome.test.listenOnce, to make this pattern easier (it
also fixes the race condition). See this for an example of it used in the tabs
API test:

http://codesearch.google.com/codesearch#OAMlx_jo-ck/src/chrome/test/data/exte...

[alexbost, 2011/09/16 20:18:14]

Bingo! (Not completely sure if it will work in my case but I will give it a
better try later.)

+      function (tabId, changeInfo, tab) {
+        chrome.experimental.offscreenTabs.onUpdated.removeListener(listener);
+
+        assertEq(inTabs[0].url, changeInfo.url);
+        assertEq(inTabs[0].url, tab.url);
+        assertEq(inTabs[0].width, tab.width);
+        assertEq(inTabs[0].height, tab.height);
+
+        tabMouse = tab;
+
+        mouseClick();
+    });
+
+  chrome.experimental.offscreenTabs.create(
+      { "url":inTabs[0].url,
+        "width":inTabs[0].width,
+        "height":inTabs[0].height
+      }
+    );
+}
+
+function mouseClick() {
+  chrome.experimental.offscreenTabs.onUpdated.addListener(listener =
+      function(tabId, changeInfo, tab) {
+        chrome.experimental.offscreenTabs.onUpdated.removeListener(listener);
+
+        assertEq(tabMouse.id, tabId);
+        assertEq(tabMouse.id, tab.id);
+        assertEq(inTabs[1].url, changeInfo.url);
+        assertEq(inTabs[1].url, tab.url);
+        assertEq(tabMouse.width, tab.width);
+        assertEq(tabMouse.height, tab.height);
+
+        mouseWheel();
+    });
+
+  mouseEvent.type = "click";
+  chrome.experimental.offscreenTabs.
+      sendMouseEvent(tabMouse.id, mouseEvent, x, y);
+}
+
+function mouseWheel() {
+  mouseEvent.type = "mousewheel";
+  mouseEvent.wheelDeltaX = 0;
+  mouseEvent.wheelDeltaY = -100;
+  chrome.experimental.offscreenTabs.
+      sendMouseEvent(tabMouse.id, mouseEvent, 0, 0, function(tab) {
+          mouseDownUp();
+        }
+    );
+}
+
+function mouseDownUp() {
+  chrome.experimental.offscreenTabs.onUpdated.addListener(listener =
+      function(tabId, changeInfo, tab) {
+        chrome.experimental.offscreenTabs.onUpdated.removeListener(listener);
+
+        assertEq(inTabs[2].url, tab.url);
+
+        removeMouse();
+    });
+
+  mouseEvent.type = "mousedown";
+  chrome.experimental.offscreenTabs.
+      sendMouseEvent(tabMouse.id, mouseEvent, x, y);
+
+  mouseEvent.type = "mouseup";
+  chrome.experimental.offscreenTabs.
+      sendMouseEvent(tabMouse.id, mouseEvent, x, y);
+}
+
+function removeMouse() {

[jstritar, 2011/09/16 16:03:50]

see comments about removeKeyboard

[alexbost, 2011/09/16 20:18:14]

Done.

+  chrome.experimental.offscreenTabs.remove(tabMouse.id);
+
+  verifyTabDoesNotExist(tabMouse.id);
+}
+
+// Keyboard --------------------------------------------------------------------
+
+function startKeyboardEvents() {
+  chrome.experimental.offscreenTabs.onUpdated.addListener(listener =

[jstritar, 2011/09/16 16:03:50]

chrome.test.listenOnce

[jstritar, 2011/09/16 16:03:50]

Why do you wait for onUpdated here? Why not just call keyPress from inside
create's callback? Are you testing that onUpdated is invoked when creating an
offscreen tab?

[alexbost, 2011/09/16 20:18:14]

Done.

[alexbost, 2011/09/16 20:18:14]

Because create might return before the page has navigated. We should probably
return once it has navigated. I will add a TODO in the module .cc file.

+      function(tabId, changeInfo, tab) {
+        chrome.experimental.offscreenTabs.onUpdated.removeListener(listener);
+
+        tabKeyboard = tab;
+
+        keyPress();
+    });
+
+  chrome.experimental.offscreenTabs.create(
+      { "url":inTabs[0].url,
+        "width":inTabs[0].width,
+        "height":inTabs[0].height
+      }
+    );

[jstritar, 2011/09/16 16:03:50]

I'm not sure about this but it's probably safer to just have a callback here to
make sure the test waits properly. 

chrome.experimental.offscreenTabs.create({}, pass(function() {
  assertTrue(true)
}));

[alexbost, 2011/09/16 20:18:14]

I had some trouble using the pass function with the way my tests are set up, so
I left it out.

+}
+
+function keyPress() {
+  chrome.experimental.offscreenTabs.onUpdated.addListener(listener =

[jstritar, 2011/09/16 16:03:50]

ditto on chrome.test.listenOnce

[alexbost, 2011/09/16 20:18:14]

Done.

+      function(tabId, changeInfo, tab) {
+        chrome.experimental.offscreenTabs.onUpdated.removeListener(listener);
+
+        assertEq(inTabs[1].url, tab.url);
+
+        removeKeyboard();
+    });
+
+  var keyboardEvent = {
+    "type":"keypress",
+    "charCode":113,  // q
+    "keyCode":113,
+    "altKey":false,
+    "ctrlKey":false,
+    "shiftKey":false
+  };
+
+  chrome.experimental.offscreenTabs.
+      sendKeyboardEvent(tabKeyboard.id, keyboardEvent);
+}
+
+function removeKeyboard() {

[jstritar, 2011/09/16 16:03:50]

I don't think this needs to be its own method since it's only called from one
place and the API call is pretty self explanatory.

[alexbost, 2011/09/16 20:18:14]

Done.

+  chrome.experimental.offscreenTabs.remove(tabKeyboard.id);
+
+  verifyTabDoesNotExist(tabKeyboard.id);

[jstritar, 2011/09/16 16:03:50]

There's a race condition here. The tab may not really be removed until the
callback is invoked.

chrome.experimental.offscreenTabs.remove(tabKeyboard.id, pass(function() {
  verifyTabDoesNotExist(tabKeyboard.id);
}));

[alexbost, 2011/09/16 20:18:14]

Done. BTW, I think there is a bug in the tabs API - remove doesn't return a
callback.

+}
+
+// toDataUrl -------------------------------------------------------------------
+
+// In order to test that we don't get empty images back we can compare two
+// images that are supposed to be different. We only need to make sure the two
+// offscreen tabs have the same size (i.e. inTabs[0] and inTabs[1])
+function startToDataUrl() {
+  var nCallbacksNotDone = nTabsCaptured;
+
+  for (var i=0; i<nTabsCaptured; i++) {
+    chrome.experimental.offscreenTabs.create(
+      { "url":inTabs[i].url,
+        "width":inTabs[i].width,
+        "height":inTabs[i].height
+      },
+      function() {
+        var j = i;
+        return function(tab) {
+          tabsCaptured[j] = tab;
+
+          nCallbacksNotDone--;
+
+          if (nCallbacksNotDone == 0)
+             toDataUrl();
+        }
+      }()
+    );
+  }
+}
+
+function toDataUrl() {
+  var nCallbacksNotDone = nTabsCaptured;
+
+  for (var i=0; i<nTabsCaptured; i++) {
+    chrome.experimental.offscreenTabs.toDataUrl(
+        tabsCaptured[i].id,
+        {"format":"png"},
+        function(dataUrl) {
+          var j = i;
+          return function(dataUrl) {
+            assertEq('string', typeof(dataUrl));
+            assertEq('data:image/png;base64,', dataUrl.substr(0,22));
+
+            tabsCaptured[j].dataUrl = dataUrl;
+
+            nCallbacksNotDone--;
+
+            if (nCallbacksNotDone == 0) {
+              // Compare the dataUrls
+              assertTrue(tabsCaptured[0].dataUrl != tabsCaptured[1].dataUrl);
+
+              removeToDataUrl();
+            }
+          }
+        }()
+      );
+  }
+}
+
+function removeToDataUrl() {
+  for (var i=0; i<nTabsCaptured; i++) {
+    chrome.experimental.offscreenTabs.remove(tabsCaptured[i].id);
+
+    verifyTabDoesNotExist(tabsCaptured[i].id);
+  }
+}
+
+// Run tests  ------------------------------------------------------------------
+
+function run() {

[jstritar, 2011/09/16 16:03:50]

You don't need the run() method-- the chrome.test.runTests part will start the
test.

[alexbost, 2011/09/16 20:18:14]

Done.

+chrome.test.runTests([
+  function tabManagement() {

[jstritar, 2011/09/16 16:03:50]

I think you have race conditions in these tests- the test runner will move on to
the next test while you're waiting for the callbacks to fire.

We have a helper method, chrome.test.callbackPass, to handle this situation. You
wrap your callback functions with it and the test runner will count how many
callbacks you have and wait for them to be executed before moving on to the next
test.

They would look like this since you've assigned callbackPass to pass:

chrome.experimental.offscreenTabs.toDataUrl(..., pass(function(dataUrl) {

}));

[alexbost, 2011/09/16 20:18:14]

Unfortunately, I haven't been able to use the pass function successfully in my
tests. I actually get synchronicity problems if I do use it. I.e. I would get
"All tests succeeded" multiple times or even when tests fail. Maybe there is
something wrong with my general setup? But, right now the tests seem to run one
after the other as opposed to in parallel, so I don't think there are race
conditions.

[jstritar, 2011/09/16 21:02:41]

I do think you need them. The timing issue could show up as intermittent
failures. You can get the 'all tests succeed' multiple times if one of the
callbacks wrapped in pass() get's called multiple times-- basically each time
you call pass, the callback should be invoked once. You don't wrap the event
handler function with a pass when using chrome.test.listenOnce - maybe that was
the problem (listenOnce will handle it for you)?

Have you tried running the test like 10 or so times and see if it fails at all?
I just patched it in and every now and then got this failure:


[32445:32445:0916/165218:193549294384:INFO:CONSOLE(51)] "[FAIL] undefined: FAIL
(no message)
    at Object.assertBool (chrome/extensionapitest:121:19)
    at chrome/extensionapitest:105:17
    at Object.callback
(chrome-extension://eeaadflfhcmafcpahlhlnkpommkklcch/test.js:322:13)
    at Object.<anonymous> (chrome/ExtensionProcessBindings:120:19)", source:
chrome/extensionapitest (51)
[32445:32445:0916/165218:193549294541:INFO:CONSOLE(23)] "Uncaught completed",
source: chrome/extensionapitest (23)
../../chrome/browser/extensions/extension_offscreen_tabs_apitest.cc:18: Failure
Value of: RunExtensionTest("offscreen_tabs")
  Actual: false
Expected: true
FAIL (no message)
    at Object.assertBool (chrome/extensionapitest:121:19)
    at chrome/extensionapitest:105:17
    at Object.callback
(chrome-extension://eeaadflfhcmafcpahlhlnkpommkklcch/test.js:322:13)
    at Object.<anonymous> (chrome/ExtensionProcessBindings:120:19)

I think this is pretty important because these will be run on the main waterfall
even if it's behind the experimental flag.

[alexbost, 2011/09/16 21:46:53]

This error is caused by create returning before the offscreen tab has navigated.
I have added a TODO in the module .cc file. The toDataUrl is (now) called in an
onUpdated event. We still need to figure out the callbackPass...

[jstritar, 2011/09/16 22:14:22]

Okay, as long as the tests are passing now, I can figure out the callbackPass
part later.

+    startTabManagement();

[jstritar, 2011/09/16 16:03:50]

I think these tests would be easier to follow if you call the offscreenTab APIs
directly from these methods, rather than jumping to the helpers. (I may be wrong
though since you might get too much indentation. It's up to you!)

You can see examples of our test style in these tab tests (each of those html
files is a little test suite, so there are lots of examples there):

http://codesearch.google.com/codesearch#OAMlx_jo-ck/src/chrome/test/data/exte...

[alexbost, 2011/09/16 20:18:14]

Yes, I tried to stay away from the multiple levels of indentation. For example
the Tab Management would have 5 levels.

+  }
+  ,

[jstritar, 2011/09/16 16:03:50]

nit: comma right after the '}' like this },

[alexbost, 2011/09/16 20:18:14]

Done.

+  function mouseEvents() {

[jstritar, 2011/09/16 16:03:50]

Can you add comments to each of these to make clear what you're testing?

[alexbost, 2011/09/16 20:18:14]

Done.

+    startMouseEvents();
+  }
+  ,
+  function keyboardEvents() {
+    startKeyboardEvents();
+  }
+  ,
+  function toDataUrl() {
+    startToDataUrl();
+  }
+]);
+}
+
+run();
+
Property changes on: chrome/test/data/extensions/api_test/offscreen_tabs/test.js
___________________________________________________________________
Added: svn:eol-style
   + LF