/* ***** BEGIN LICENSE BLOCK *****

  * Version: MPL 1.1/GPL 2.0/LGPL 2.1

  *

  * The contents of this file are subject to the Mozilla Public License Version

  * 1.1 (the "License"); you may not use this file except in compliance with

  * the License. You may obtain a copy of the License at

  * http://www.mozilla.org/MPL/

  *

  * Software distributed under the License is distributed on an "AS IS" basis,

  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License

  * for the specific language governing rights and limitations under the

  * License.

  *

  * The Original Code is Pending Events Test Harness.

  *

  * The Initial Developer of the Original Code is

  * Alexander J. Vincent <ajvincent@gmail.com>.

  * Portions created by the Initial Developer are Copyright (C) 2010

  * the Initial Developer. All Rights Reserved.

  *

  * Contributor(s):

  *

  * Alternatively, the contents of this file may be used under the terms of

  * either the GNU General Public License Version 2 or later (the "GPL"), or

  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),

  * in which case the provisions of the GPL or the LGPL are applicable instead

  * of those above. If you wish to allow use of your version of this file only

  * under the terms of either the GPL or the LGPL, and not to allow others to

  * use your version of this file under the terms of the MPL, indicate your

  * decision by deleting the provisions above and replace them with the notice

  * and other provisions required by the GPL or the LGPL. If you do not delete

  * the provisions above, a recipient may use your version of this file under

  * the terms of any one of the MPL, the GPL or the LGPL.

  *

  * ***** END LICENSE BLOCK ***** */

 /*

 This object exists to manage tests which depend on asynchronous events firing

 before the test completes.  For example, if you wish to test properties of a XBL

 binding on an element, but the element hasn't been inserted into a live user

 document, you would want to pause the test and allow the binding to attach.  You

 would also want to specify a "resume ordinary testing" point.

 This test harness accepts test parts as individual functions.  Add a test

 function by calling PendingEventsTest.addTest(yourFunction).  At all exit points

 for a test, you should call PendingEventsTest.asyncRun().  To start the test

 sequence, call PendingEventsTest.run().

 To block one test function from running because you're waiting for a DOM event,

 call PendingEventsTest.addEventLock.  Tests will not proceed until the right

 DOM event arrives.  If the right DOM event does not arrive in the time you

 specify, the test will fail.

 To transfer local variables from one test function to another, use the

 setPayload(), getPayload() and clearPayload() methods.

 You can add functions which execute after the overall test script finishes

 (with failure or success) using the executeAfterRun() method.

 Finally, to abort a test run with a failure (and prevent other asynchronous test

 functions from running), use the abortFail() method.  Once this method is called,

 the test script is effectively done.  The abortFail() method will also trigger

 for exceptions not caught in the test script.

 */

 Components.utils.import("resource://gre/modules/XPCOMUtils.jsm");

 SimpleTest.waitForExplicitFinish();

 const PendingEventsTest = {

   _tests: [],

   _locks: [],

   _payload: null,

   _aborted: false,

   _postRunCallbacks: [],

   _endTests: function() {

     for each (var callback in this._postRunCallbacks)

     {

       try {

         callback();

       } catch (e) {

         ok(false, e);

       }

     }

     SimpleTest.finish();

     window.onerror = gOldOnError;

   },

   /**

    * Prevent the test from proceeding until an event has been received.

    *

    * @param node      The DOM node expecting an event.

    * @param eventName The name of the event.

    * @param capturing True if the event should be in the capturing phase.

    * @param timeLimit The number of milliseconds to wait for the event.  If not

    *                  received in that time, the test has failed.

    * @param filter    (optional) A JS function which filters events passed to

    *                  the event listener.  The function takes the event as its

    *                  first argument.  If the function returns false, the lock

    *                  ignores the event.

    * @param subtest   (optional) A custom test to run in handleEvent.  The

    *                  function takes the event as its first argument.

    */

   addEventLock: function(node, eventName, capturing, timeLimit, filter, subtest)

   {

     if (!(node instanceof C_i.nsIDOMNode) ||

         (typeof eventName != "string") ||

         (typeof capturing != "boolean") ||

         (typeof timeLimit != "number") ||

         (filter && (typeof filter != "function")) ||

         (subtest && (typeof subtest != "function")))

     {

       throw new Components.Exception("Event lock argument is invalid",

                                      Components.results.NS_ERROR_ILLEGAL_VALUE);

     }

     if (isNaN(timeLimit) ||

         (timeLimit <= 0) ||

         (timeLimit == Infinity))

     {

       throw new Components.Exception("timeLimit is an invalid value",

                                      Components.results.NS_ERROR_ILLEGAL_VALUE);

     }

     const lock = {

       timeout: function()

       {

         if (PendingEventsTest._aborted)

           return;

         PendingEventsTest.abortFail("Expected " + eventName + " event, timed out");

       },

       // nsIDOMEventListener

       handleEvent: function(event)

       {

         if (PendingEventsTest._aborted)

           return;

         // Does the event apply to this lock?

         try {

           if (filter && !filter(event))

             return;

         }

         catch (e) {

           PendingEventsTest.abortFail("exception caught in lock filter: " + e);

           return;

         }

         window.clearTimeout(this._timer);

         event.currentTarget.removeEventListener(eventName, this, capturing);

         try {

           if (subtest)

           {

             subtest();

           }

         }

         catch (e) {

           PendingEventsTest.abortFail("exception caught in subtest: " + e);

           if (typeof e.stack == "string")

           {

             dump(e.stack + "\n\n");

           }

           throw e;

         }

         var index = PendingEventsTest._locks.indexOf(this);

         PendingEventsTest._locks.splice(index, 1);

         PendingEventsTest.run();

       },

       // nsISupports

       QueryInterface:

       XPCOMUtils.generateQI(["nsIDOMEventListener"])

     };

     PendingEventsTest._locks.push(lock);

     lock._timer = window.setTimeout(function() {

       lock.timeout();

     }, timeLimit);

     node.addEventListener(eventName, lock, capturing);

   },

   /**

    * Add a test to the execution sequence.

    */

   addTest: function(aTest)

   {

     this._tests.push(aTest);

   },

   /**

    * Abort the test run and log a failure.

    *

    * @param msg The failure message to log.

    */

   abortFail: function(msg) {

     this._aborted = true;

     ok(false, msg);

     this._endTests();

   },

   /**

    * Get an object which a previous test stored, after checking its name.

    *

    * @param nameCheck The name to match against the previous payload store.

    *

    * @returns The object the user cached.

    */

   getPayload: function(nameCheck)

   {

     if (!this._payload)

     {

       throw new Components.Exception(

         "No payload!",

         Components.results.NS_ERROR_NOT_INITIALIZED

       );

     }

     if (nameCheck != this._payload.name)

     {

       throw new Components.Exception(

         "Payload name didn't match: " + this._payload.name,

         Components.results.NS_ERROR_UNEXPECTED

       )

     }

     return this._payload.data;

   },

   /**

    * Store an object for a later test to pick up.

    *

    * @param name A value to confirm the right parties get the right payload.

    * @param data The object to store.

    */

   setPayload: function(name, data)

   {

     if (this._payload)

     {

       throw new Components.Exception(

         "We already have a payload!",

         Components.results.NS_ERROR_ALREADY_INITIALIZED

       );

     }

     this._payload = {

       name: name,

       data: data

     };

   },

   /**

    * Clear the stored object, after checking its name.

    *

    * @param nameCheck The name to match against the previous payload store.

    */

   clearPayload: function(nameCheck)

   {

     if (!this._payload)

     {

       throw new Components.Exception(

         "No payload!",

         Components.results.NS_ERROR_NOT_INITIALIZED

       );

     }

     if (nameCheck != this._payload.name)

     {

       throw new Components.Exception(

         "Payload name didn't match: " + this._payload.name,

         Components.results.NS_ERROR_UNEXPECTED

       )

     }

     this._payload = null;

   },

   /**

    * Run the next test, if there are no locks and we haven't aborted.

    */

   run: function PendingEventsTest_run()

   {

     if ((this._locks.length > 0) || (this._aborted))

     {

       return;

     }

     if (this._tests.length > 0)

     {

       var test = this._tests.shift();

       try {

         test();

       } catch (e) {

         this.abortFail(e);

       }

       return;

     }

     this._endTests();

   },

   /**

    * Run the next test asynchronously, so as to allow currently executing

    * functions to exit cleanly (and not show up on the stack).

    */

   asyncRun: function() {

     var delay = (arguments.length > 0) ? arguments[0] : 0;

     if (isNaN(delay) || (delay < 0) || (delay == Infinity))

     {

       throw new Components.Exception(

         "PendingEventsTest.asyncRun called with bad delay",

         Components.results.NS_ERROR_ILLEGAL_VALUE

       );

     }

     window.setTimeout("PendingEventsTest.run()", delay);

   },

   /**

    * Execute a function after the test run finishes (successfully or not).

    */

   executeAfterRun: function(callback)

   {

     if (typeof callback != "function")

       throw new Components.Exception("executeAfterRun expects a function",

                                      Components.results.NS_ERROR_ILLEGAL_VALUE);

     this._postRunCallbacks.push(callback);

   }

 };