[whatwg] Web author docs for postMessage, updated postMessage tests

[Jeff Walden]

== Documentation ==

I've written up some documentation on how to use postMessage; suggestions, comments, etc. appreciated.

http://developer.mozilla.org/en/docs/DOM:window.postMessage


== Tests ==

I updated and expanded the tests I posted earlier to accommodate uri/domain->origin and the optional targetOrigin argument to postMessage:

http://web/jwalden/www/whatwg/postMessage-v2.zip

Same rules for use apply as before -- unzip somewhere, start up a local web server on port 8888 serving the postMessage/ directory as its root directory, turn on proxy autoconfig with the URL <http://localhost:8888/proxy.js>, and load and run <http://localhost:8888/tests/dom/tests/mochitest/whatwg/index.html> to see what passes and fails.

The tests basically follow the spec or guard Mozilla-specific tests assuming you follow the spec.  There are some cases where Mozilla doesn't follow the spec, however, and won't be able to do so before Mozilla 2, so unless you fail those tests exactly like Mozilla does they'll show up as failures when you run the tests.

First, most of the problems you'll likely encounter relate to the value of .origin for IDN origins.  HTML5 is silent on whether the value should be IDN, punycode, or even a chimeric mixture.  I think .origin should never be punycode (authors shouldn't be forced to know about punycode, allowing either would require multiple origin comparisons, and also, Unicode > ASCII), and the tests expect that (or, for the places where we fail that, they expect the opposite and mark that situation as a "todo").  If you do anything other than exactly match Mozilla behavior, you'll see tests listed as failures.

Second, test_postMessage_closed.html fails if a popup blocker is enabled.  Make sure to run this with the blocker disabled to actually make it do its tests right.

Third, the tests require a very strict parsing of the optional targetOrigin argument to postMessage which rejects various malformed URIs.  Unless you match Mozilla's behavior exactly, you'll see some errors here -- some quite likely erroneous.  Note also that some of these tests check handling when this argument is punycode and when it's IDN; make sure you pass both.  I apologize in advance if you find test_postMessage_origin.xhtml a little confusing to read; I don't especially like it either.  However, it was the easiest way I could think of to run a whole lot of similar tests without lots of code-copying.  I'm guessing existing URL parsers are lax because existing content is lax; for postMessage there's no existing content, so I'd like to see this done right from the start (or at least described that way in the spec, since Mozilla isn't in a position to switch to stricter parsing until Mozilla 2).

Fourth, .origin for posts from data: URIs in Mozilla is the origin of the window that opened the data: URL, which is not what HTML5 wants (data: URLs each have origins distinct from all other origins in existence).  Mozilla really isn't in a position to make a change to such fundamental security-conscious code right now, so this is expected to fail and marked as todo.  If you do the right thing or don't do what we do, you'll get a failure on test_postMessage_special.xhtml.  (I've documented Mozilla's behavior at the aforementioned link and noted that it's all but certainly going to change, and I've discouraged authors from using postMessage on pages at data: URIs for now.  This isn't optimal, but I don't really think it's that huge a burden.)

Fifth, I interpreted "present and not null" to mean that an explicit |undefined| second argument is converted to the string "undefined" and thus causes a syntax error to be thrown, based on a literal interpretation of the words in the phrase.

Comments, questions, suggestions for more tests, etc. are all appreciated.

Jeff