source: Dev/trunk/src/client/dojo/robotx.js @ 487

define([
        "require",
        "doh/main",
        "./aspect",
        "./dom-construct",
        "./dom-style",
        "./_base/kernel",
        "./_base/lang",
        "./on",
        "./robot",
        "./sniff",
        "./_base/window"
], function(require, doh, aspect, construct, style, kernel, lang, on, robot, has, win){

kernel.experimental("dojo.robotx");

// module:
//              dojo.robotx
// description:
//              loads an external app into an iframe and points dojo.doc to the iframe document, allowing the robot to control it
//              to use: set robotURL in djConfig to the URL you want to load
//              dojo.require this file

// The iframe containing the external app
var iframe = null;

// On IE6/7, a firebug console will appear.   Scrunch it a bit to leave room for the external test file.
kernel.config.debugHeight = kernel.config.debugHeight || 200;


// urlLoaded is a Deferred that will be resolved whenever the iframe passed to initRobot() finishes loading, or reloads
var urlLoaded;

function attachIframe(url){
        // summary:
        //              Create iframe to load external app at specified url.   Iframe gets onload handler to  call onIframeLoad()
        //              when specified URL finishes loading, and also if the iframe loads a different URL in the future.
        // returns:
        //              A Deferred that fires when everything has finished initializing

        require(["./domReady!"], function(){
                var emptyStyle = {
                        overflow: "hidden",
                        margin: "0px",
                        borderWidth: "0px",
                        height: "100%",
                        width: "100%"
                };
                style.set(document.documentElement, emptyStyle);
                style.set(document.body, emptyStyle);

                // Create the iframe for the external document.   Put it above the firebug-lite div (if such a div exists).
                // console.log("creating iframe for external document");
                iframe = document.createElement("iframe");
                iframe.setAttribute("ALLOWTRANSPARENCY","true");
                iframe.scrolling = has("ie") ? "yes" : "auto";
                var scrollRoot = document.compatMode == "BackCompat" ? document.body : document.documentElement;
                var consoleHeight = (document.getElementById("firebug") || {}).offsetHeight || 0;
                style.set(iframe, {
                        border: "0px none",
                        padding: "0px",
                        margin: "0px",
                        width: "100%",
                        height: consoleHeight ? (scrollRoot.clientHeight - consoleHeight)+"px" : "100%"
                });
                iframe.src = url;

                // Code to handle load event on iframe.  Seems like this should happen before setting iframe src on line above?
                // Also, can't we use on() in all cases, even for old IE?
                if(iframe.attachEvent !== undefined){
                        iframe.attachEvent("onload", onIframeLoad);
                }else{
                        on(iframe, "load", onIframeLoad);
                }

                construct.place(iframe, win.body(), "first");
        });
}

function onIframeLoad(){
        // summary:
        //              Load handler when iframe specified to initRobot() finishes loading, or when it reloads.
        //              It resolves the urlLoaded Deferred to make the rests of the tests runs.

        robot._updateDocument();

        // If dojo is present in the test case, then at least make a best effort to wait for it to load.
        // The test must handle other race conditions like initial data queries or asynchronous parses by itself.
        if(iframe.contentWindow.require){
                iframe.contentWindow.require(["dojo/ready"], function(ready){
                        ready(Infinity, function(){
                                setTimeout(function(){
                                        urlLoaded.resolve(true);
                                }, 500);        // 500ms fudge factor; otherwise focus doesn't work on IE8, see ValidationTextBox.js, TimeTextBox.js, etc.
                        });
                });
        }else{
                urlLoaded.resolve(true);
        }
}

lang.mixin(robot, {
        _updateDocument: function(){
                // summary:
                //              Called every time a new page is loaded into the iframe, to setup variables
                //              Point dojo.global, dojo.publish, etc. to refer to iframe.
                //              Remove for 2.0?

                kernel.setContext(iframe.contentWindow, iframe.contentWindow.document);

                // Also set pointers inside robot, for easy access via AMD (where there is no dojo variable)
                robot.window = iframe.contentWindow;
                robot.doc = iframe.contentWindow.document;

                // TODO: shouldn't this wait until dojo has finished loading in the iframe?  See require code in onIframeLoad().
                var win = kernel.global;
                if(win.dojo){
                        // allow the tests to subscribe to topics published by the iframe
                        kernel.publish = win.dojo.publish;
                        kernel.subscribe = win.dojo.subscribe;
                        kernel.connectPublisher = win.dojo.connectPublisher;
                }
        },

        initRobot: function(/*String*/ url){
                // summary:
                //              Opens the application at the specified URL for testing, redirecting dojo to point to the application
                //              environment instead of the test environment.
                // url:
                //              URL to open. Any of the test's dojo.doc calls (e.g. dojo.byId()), and any dijit.registry calls
                //              (e.g. dijit.byId()) will point to elements and widgets inside this application.

                doh.registerGroup("initialize robot", {
                        name: "load " + url,
                        timeout: 100000,        // could take more than 10s so setting to 100s
                        runTest: function(){
                                // Setup module level urlLoaded Deferred that will be resolved by onIframeLoad(), after the iframe
                                // has finished loading
                                urlLoaded = new doh.Deferred();
                                attachIframe(url);

                                return urlLoaded;
                        }
                });
        },

        waitForPageToLoad: function(/*Function*/ submitActions){
                // summary:
                //              Notifies DOH that the doh.robot is about to make a page change in the application it is driving,
                //              returning a doh.Deferred object the user should return in their runTest function as part of a DOH test.
                // example:
                // |    runTest: function(){
                // |            return waitForPageLoad(function(){ doh.robot.keyPress(keys.ENTER, 500); });
                // |    }
                // submitActions:
                //              The doh.robot will execute the actions the test passes into the submitActions argument (like clicking the submit button),
                //              expecting these actions to create a page change (like a form submit).
                //              After these actions execute and the resulting page loads, the next test will start.

                // Setup a new Deferred that onIframeLoad() will resolve when the iframe finishes loading
                urlLoaded = new doh.Deferred();

                submitActions();

                return urlLoaded;
        }

});

return robot;
});