Firebug Automated Test API

From FirebugWiki

(Difference between revisions)
Jump to: navigation, search
m (Changed code blocks to use syntax highlighting)
 
(11 intermediate revisions not shown)
Line 1: Line 1:
-
[http://getfirebug.com/wiki/index.php/Running_Automated_Test_Suite Running Automated Test Suite]
 
-
 
-
 
== FBTest Object ==
== FBTest Object ==
-
A test, specifically the test driver part, usually use APIs that are provided by the FBTest framework. The test driver uses them to communicate back to the framework and automate Browser and Firebug UI. All APIs are accessible via FBTest object that is automatically defined as a global variable within a test driver scope. Let's see what methods are available
+
A test, specifically the test driver part, usually use APIs that are provided by the [[FBTest]] framework. The test driver uses them to communicate back to the framework and automate Browser and Firebug UI. All APIs are accessible via FBTest object that is automatically defined as a global variable within a test driver scope. Let's see what methods are available:
-
 
+
* <code>ok(pass, msg)</code> - generates a test report into the test console. If the first parameter is true the report is considered as passing, otherwise failing. If all reports from a test case pass, the entire test case is considered as passing, otherwise failing.
* <code>ok(pass, msg)</code> - generates a test report into the test console. If the first parameter is true the report is considered as passing, otherwise failing. If all reports from a test case pass, the entire test case is considered as passing, otherwise failing.
-
 
* <code>compare(expected, actual, msg)</code> - also generates a test report. If the expected string equals to actual, the report is considered as passing.
* <code>compare(expected, actual, msg)</code> - also generates a test report. If the expected string equals to actual, the report is considered as passing.
-
 
* <code>sysout(text, obj)</code> - prints an informative log into Firebug's tracing console. You need to have <code>TESTCASE</code> option selected.
* <code>sysout(text, obj)</code> - prints an informative log into Firebug's tracing console. You need to have <code>TESTCASE</code> option selected.
-
 
+
* <code>testDone()</code> - this method must be called at the end of each test. This informs the framework that a test has been finished.
-
* <code>testDone()</code> - this method must be called at the end of each test. This informs the framework that a test has been finished. In case of Firebug tests, FBTestFirebug.testDone(msg) should be used. See below.
+
-
 
+
* <code>progress(msg)</code> - prints an informative message into the Test console status bar.
* <code>progress(msg)</code> - prints an informative message into the Test console status bar.
-
 
-
* <code>click(node)</code> - fires a click event on specified DOM node.
 
-
 
-
* <code>focus(node)</code> - focuses specified DOM node. Either using a focus method or firing a DOMFocusIn event on the node.
 
-
 
-
* <code>mouseDown(node)</code> - fires a mousedown event on specified DOM node.
 
-
 
* <code>loadScript(scriptURI, scope)</code> - loads additional script file.
* <code>loadScript(scriptURI, scope)</code> - loads additional script file.
-
 
* <code>getHTTPURLBase()</code> - returns base path of the local HTTP server (e.g. http://localhost:7080/).
* <code>getHTTPURLBase()</code> - returns base path of the local HTTP server (e.g. http://localhost:7080/).
-
 
* <code>getLocalURLBase()</code> - returns local path of the home server directory (e.g. C:\firebug\tests\content\)
* <code>getLocalURLBase()</code> - returns local path of the home server directory (e.g. C:\firebug\tests\content\)
-
 
* <code>exception(message, err)</code> - generates an exception report into the test console. This report is always marked as failing.
* <code>exception(message, err)</code> - generates an exception report into the test console. This report is always marked as failing.
-
 
+
* <code>resetTimeout()</code> - resets the timeout, so test cases, which take longer to execute, won't run into a timeout
=== Example of exception logging ===
=== Example of exception logging ===
-
 
+
<source lang="javascript">
-
<pre>
+
function runTest()
function runTest()
{
{
Line 50: Line 31:
     }
     }
}
}
-
</pre>
+
</source>
-
 
+
-
 
+
-
== FBTestFirebug Object ==
+
-
There is another set of APIs that are intended to be used by test for Firebug or Firebug extensions. All these methods are available via FBTestFirebug object that is also automatically defined as a global variable in every test driver scope.
+
-
 
+
=== Firebug UI ===
=== Firebug UI ===
* <code>openFirebug()</code> - opens Firebug UI as a bar at the bottom of the Firefox Window (reffered as the Firebug Window).
* <code>openFirebug()</code> - opens Firebug UI as a bar at the bottom of the Firefox Window (reffered as the Firebug Window).
-
 
* <code>closeFirebug()</code> - closes Firebug UI.
* <code>closeFirebug()</code> - closes Firebug UI.
-
 
* <code>pressToggleFirebug(forceOpen)</code> - toggles (open/close) Firebug UI.
* <code>pressToggleFirebug(forceOpen)</code> - toggles (open/close) Firebug UI.
-
 
* <code>detachFirebug()</code> - detaches Firebug from the Firebug Window.
* <code>detachFirebug()</code> - detaches Firebug from the Firebug Window.
-
 
* <code>isFirebugOpen()</code> - returns true if Firebug is currently opened.
* <code>isFirebugOpen()</code> - returns true if Firebug is currently opened.
-
 
* <code>closeFirebugOnAllTabs()</code> - closes Firebug UI on all tabs.
* <code>closeFirebugOnAllTabs()</code> - closes Firebug UI on all tabs.
-
 
=== Firebug Activation ===
=== Firebug Activation ===
-
Helpers for panel acivation (enablement)
+
Helpers for panel activation (enablement)
-
 
+
-
* <code>enableNetPanel(callback)</code>
+
-
* <code>disableNetPanel(callback)</code>
+
-
* <code>enableScriptPanel(callback)</code>
+
-
* <code>disableScriptPanel(callback)</code>
+
-
* <code>enableConsolePanel(callback)</code>
+
-
* <code>disableConsolePanel(callback)</code>
+
-
* <code>disableAllPanels()</code>
+
-
* <code>enableAllPanels()</code>
+
 +
* <code>enableNetPanel(callback)</code> - Enables the [[Net Panel]]
 +
* <code>disableNetPanel(callback)</code> - Disables the Net Panel
 +
* <code>enableScriptPanel(callback)</code> - Enables the [[Script Panel]]
 +
* <code>disableScriptPanel(callback)</code> - Disables the Script Panel
 +
* <code>enableConsolePanel(callback)</code> - Enables the [[Console Panel]]
 +
* <code>disableConsolePanel(callback)</code> - Disables the Console Panel
 +
* <code>enableAllPanels()</code> - Enables all panels at once
 +
* <code>disableAllPanels()</code> - Disables all panels at once
 +
* <code>setPanelState(model, panelName, callbackTriggersReload, enable)</code> - Sets the state of a specific panel
=== Panels ===
=== Panels ===
Line 88: Line 58:
* <code>getSelectedPanel()</code> - returns an object that represents currently selected panel.
* <code>getSelectedPanel()</code> - returns an object that represents currently selected panel.
* <code>getPanel(panelName)</code> - returns an object that represents specified panel ("console", "script, "net", etc.).
* <code>getPanel(panelName)</code> - returns an object that represents specified panel ("console", "script, "net", etc.).
-
 
* <code>selectPanelLocationByName(panel, name)</code>
* <code>selectPanelLocationByName(panel, name)</code>
* <code>selectSourceLine(url, lineNumber, category)</code>
* <code>selectSourceLine(url, lineNumber, category)</code>
-
 
+
* <code>getPanelDocument()</code> - returns the document object of main Firebug content UI (contains all panels)
 +
* <code>getSidePanelDocument()</code> - returns the document object of the side panel Firebug content UI (contains all side panels)
 +
* <code>isPanelTabDisabled(name)</code> - returns true, if the specified panel is disabled, otherwise false
=== Preferences ===
=== Preferences ===
-
Helpers for Firebug preferences. Notice that prefName must be specified without Firebug's preference domain. See example below.
+
Helpers for [[Firebug Preferences]]. Notice that prefName must be specified without Firebug's preference domain. See example below.
* <code>setPref(prefName, value)</code>
* <code>setPref(prefName, value)</code>
* <code>getPref(prefName)</code>
* <code>getPref(prefName)</code>
-
 
+
<source lang="javascript">
-
<pre>
+
var value = FBTest.getPref("showXMLHttpRequests");
-
var value = FBTestFirebug.getPref("showXMLHttpRequests");
+
FBTest.setPref("showXMLHttpRequests", true);
-
FBTestFirebug.setPref("showXMLHttpRequests", true);
+
</source>
-
</pre>
+
In this case ''extensions.firebug.showXMLHttpRequests'' preference is used.
In this case ''extensions.firebug.showXMLHttpRequests'' preference is used.
-
 
=== Firefox ===
=== Firefox ===
-
* <code>openNewTab(url, callback)</code> - opens a new Firefox tab with specified URL. As soon as the page is loaded provied callback is executed.
+
* <code>openNewTab(url, callback)</code> - opens a new Firefox tab with the specified URL. As soon as the page is loaded provied callback is executed.
-
 
+
* <code>openURL(url, callback)</code> - opens a specified URL on the current Firefox page.
* <code>openURL(url, callback)</code> - opens a specified URL on the current Firefox page.
-
 
* <code>reload(callback)</code> - reloads the current Firefox page.
* <code>reload(callback)</code> - reloads the current Firefox page.
-
 
+
* <code>cleanUpTestTabs()</code> - closes all Firefox tabs, that have been opened as part of the testing process.
-
* <code>cleanUpTestTabs()</code> - closes all Firefox tab that have been opened as part of the testing process.
+
* <code>closeFirebugOnAllTabs()</code> - closes Firebug on all tabs
-
 
+
=== DOM ===
=== DOM ===
-
* <code>expandElements(parentNode, className [, className, ...])</code> - sends a click event to all child elements that uses specified class(s). This is useful mainly for expanding various panel contents.
+
* <code>expandElements(parentNode, className [, className, ...])</code> - sends a click event to all child elements, that use the specified class(s). This is useful mainly for expanding various panel contents.
-
 
+
-
<pre>
+
<source lang="javascript">
var panel = FW.FirebugChrome.selectPanel("net").panelNode;
var panel = FW.FirebugChrome.selectPanel("net").panelNode;
-
FBTestFirebug.expandElements(panelNode, "netRow", "category-xhr");
+
FBTest.expandElements(panelNode, "netRow", "category-xhr");
-
</pre>
+
</source>
-
Expands all XHR requests within the Net panel (sends click event to all elements that have both netRow and category-xhr classes).
+
Expands all XHR requests within the [[Net Panel]] (sends click event to all elements that have both ''netRow'' and ''category-xhr'' classes).
 +
=== Events ===
 +
* <code>click(node)</code> - fires a click event on specified DOM node
 +
* <code>dblclick(node)</code> - fires a double-click event on specified DOM node
 +
* <code>rightClick(node)</code> - fires a right-click event on specified DOM node
 +
* <code>mouseDown(node)</code> - fires a mousedown event on specified DOM node
 +
* <code>pressKey(keyCode, target)</code> - fires a key event on specified DOM node
 +
* <code>sendChar(aChar, aTarget)</code> - sends a char to specified DOM node in respect of char casing (sends shift key for uppercase chars; currently just works for English letters)
 +
* <code>sendString(aStr, aTarget)</code> - sends a string to specified DOM node (currently just works for English letters and digits)
 +
* <code>sendKey(aKey, aTarget)</code> - sends a non-char key to specified DOM node (name should be lowercase part of what comes after ''DOM_VK_'' constants)
 +
* <code>synthesizeKey(aKey, aWindow)</code> - synthesizes a key press event to whatever would be targeted by that event (typically the focused element)
 +
* <code>focus(node)</code> - focuses specified DOM node either using a focus method or firing a DOMFocusIn event on the node
=== Debugger ===
=== Debugger ===
-
* <code>clickContinueButton()</code> - simulates click on a Continue debugger button (F8)
+
* <code>clickContinueButton()</code> - simulates click on the [[Script Panel#Execution Control Buttons|Continue debugger button (F8)]]
 +
* <code>waitForBreakInDebugger(chrome, lineNo, breakpoint, callback)</code> - registers a handler for break in debugger cause by the [[Break On ...|Break On Next]] feature
 +
* <code>setBreakpoint(chrome, url, lineNo, callback)</code> - Sets a script breakpoint
 +
* <code>removeBreakpoint(chrome, url, lineNo, callback)</code> - Removes a script breakpoint
 +
=== Command Line ===
 +
* <code>executeCommand(expr, chrome)</code> - executes an expression inside the [[Command Line]]
 +
* <code>typeCommand(string, useCommandEditor)</code> - types a command into the [[Command Line]] or the Command Editor
 +
* <code>executeCommandAndVerify(callback, expression, expected, tagName, classes)</code> - executes an expression inside the Command Line and verifies the result
-
=== Miscelanous ===
+
=== Miscellaneous ===
* <code>testDone(msg)</code> - finishes a Firebug related test. This methods also closes Firebug UI, all test tabs and uses specified message as a progress mesasage in the Test console status bar.
* <code>testDone(msg)</code> - finishes a Firebug related test. This methods also closes Firebug UI, all test tabs and uses specified message as a progress mesasage in the Test console status bar.
-
 
* <code>clearCache()</code> - clear Firefox cache.
* <code>clearCache()</code> - clear Firefox cache.
 +
 +
== See also ==
 +
* [[Running Automated Test Suite]]
 +
* [[Firebug Automated Test Examples]]

Latest revision as of 08:29, 18 May 2011

Contents

[edit] FBTest Object

A test, specifically the test driver part, usually use APIs that are provided by the FBTest framework. The test driver uses them to communicate back to the framework and automate Browser and Firebug UI. All APIs are accessible via FBTest object that is automatically defined as a global variable within a test driver scope. Let's see what methods are available:

  • ok(pass, msg) - generates a test report into the test console. If the first parameter is true the report is considered as passing, otherwise failing. If all reports from a test case pass, the entire test case is considered as passing, otherwise failing.
  • compare(expected, actual, msg) - also generates a test report. If the expected string equals to actual, the report is considered as passing.
  • sysout(text, obj) - prints an informative log into Firebug's tracing console. You need to have TESTCASE option selected.
  • testDone() - this method must be called at the end of each test. This informs the framework that a test has been finished.
  • progress(msg) - prints an informative message into the Test console status bar.
  • loadScript(scriptURI, scope) - loads additional script file.
  • getHTTPURLBase() - returns base path of the local HTTP server (e.g. http://localhost:7080/).
  • getLocalURLBase() - returns local path of the home server directory (e.g. C:\firebug\tests\content\)
  • exception(message, err) - generates an exception report into the test console. This report is always marked as failing.
  • resetTimeout() - resets the timeout, so test cases, which take longer to execute, won't run into a timeout

[edit] Example of exception logging

function runTest()
{
    FBTest.sysout("exampleTest.started");
    try
    {
        hello.world(); // EXCEPTION
    }
    catch (err)
    {
        FBTest.exception("Test: ", err);
    }
    finally
    {
        FBTest.testDone();
    }
}

[edit] Firebug UI

  • openFirebug() - opens Firebug UI as a bar at the bottom of the Firefox Window (reffered as the Firebug Window).
  • closeFirebug() - closes Firebug UI.
  • pressToggleFirebug(forceOpen) - toggles (open/close) Firebug UI.
  • detachFirebug() - detaches Firebug from the Firebug Window.
  • isFirebugOpen() - returns true if Firebug is currently opened.
  • closeFirebugOnAllTabs() - closes Firebug UI on all tabs.

[edit] Firebug Activation

Helpers for panel activation (enablement)

  • enableNetPanel(callback) - Enables the Net Panel
  • disableNetPanel(callback) - Disables the Net Panel
  • enableScriptPanel(callback) - Enables the Script Panel
  • disableScriptPanel(callback) - Disables the Script Panel
  • enableConsolePanel(callback) - Enables the Console Panel
  • disableConsolePanel(callback) - Disables the Console Panel
  • enableAllPanels() - Enables all panels at once
  • disableAllPanels() - Disables all panels at once
  • setPanelState(model, panelName, callbackTriggersReload, enable) - Sets the state of a specific panel

[edit] Panels

  • selectPanel(panelName) - selects specific panel within Firebug UI.
  • getSelectedPanel() - returns an object that represents currently selected panel.
  • getPanel(panelName) - returns an object that represents specified panel ("console", "script, "net", etc.).
  • selectPanelLocationByName(panel, name)
  • selectSourceLine(url, lineNumber, category)
  • getPanelDocument() - returns the document object of main Firebug content UI (contains all panels)
  • getSidePanelDocument() - returns the document object of the side panel Firebug content UI (contains all side panels)
  • isPanelTabDisabled(name) - returns true, if the specified panel is disabled, otherwise false

[edit] Preferences

Helpers for Firebug Preferences. Notice that prefName must be specified without Firebug's preference domain. See example below.

  • setPref(prefName, value)
  • getPref(prefName)
var value = FBTest.getPref("showXMLHttpRequests");
FBTest.setPref("showXMLHttpRequests", true);

In this case extensions.firebug.showXMLHttpRequests preference is used.

[edit] Firefox

  • openNewTab(url, callback) - opens a new Firefox tab with the specified URL. As soon as the page is loaded provied callback is executed.
  • openURL(url, callback) - opens a specified URL on the current Firefox page.
  • reload(callback) - reloads the current Firefox page.
  • cleanUpTestTabs() - closes all Firefox tabs, that have been opened as part of the testing process.
  • closeFirebugOnAllTabs() - closes Firebug on all tabs

[edit] DOM

  • expandElements(parentNode, className [, className, ...]) - sends a click event to all child elements, that use the specified class(s). This is useful mainly for expanding various panel contents.
var panel = FW.FirebugChrome.selectPanel("net").panelNode;
FBTest.expandElements(panelNode, "netRow", "category-xhr");

Expands all XHR requests within the Net Panel (sends click event to all elements that have both netRow and category-xhr classes).

[edit] Events

  • click(node) - fires a click event on specified DOM node
  • dblclick(node) - fires a double-click event on specified DOM node
  • rightClick(node) - fires a right-click event on specified DOM node
  • mouseDown(node) - fires a mousedown event on specified DOM node
  • pressKey(keyCode, target) - fires a key event on specified DOM node
  • sendChar(aChar, aTarget) - sends a char to specified DOM node in respect of char casing (sends shift key for uppercase chars; currently just works for English letters)
  • sendString(aStr, aTarget) - sends a string to specified DOM node (currently just works for English letters and digits)
  • sendKey(aKey, aTarget) - sends a non-char key to specified DOM node (name should be lowercase part of what comes after DOM_VK_ constants)
  • synthesizeKey(aKey, aWindow) - synthesizes a key press event to whatever would be targeted by that event (typically the focused element)
  • focus(node) - focuses specified DOM node either using a focus method or firing a DOMFocusIn event on the node

[edit] Debugger

  • clickContinueButton() - simulates click on the Continue debugger button (F8)
  • waitForBreakInDebugger(chrome, lineNo, breakpoint, callback) - registers a handler for break in debugger cause by the Break On Next feature
  • setBreakpoint(chrome, url, lineNo, callback) - Sets a script breakpoint
  • removeBreakpoint(chrome, url, lineNo, callback) - Removes a script breakpoint

[edit] Command Line

  • executeCommand(expr, chrome) - executes an expression inside the Command Line
  • typeCommand(string, useCommandEditor) - types a command into the Command Line or the Command Editor
  • executeCommandAndVerify(callback, expression, expected, tagName, classes) - executes an expression inside the Command Line and verifies the result

[edit] Miscellaneous

  • testDone(msg) - finishes a Firebug related test. This methods also closes Firebug UI, all test tabs and uses specified message as a progress mesasage in the Test console status bar.
  • clearCache() - clear Firefox cache.

[edit] See also

Personal tools