Skip to content

Latest commit

 

History

History
263 lines (152 loc) · 7.57 KB

QFrame.md

File metadata and controls

263 lines (152 loc) · 7.57 KB
Raw

Quixote API: QFrame

QFrame controls the test frame. You'll use this to create and retrieve elements. Of particular use is frame.reset(), which you should call before each test. You'll also call frame.remove() after all your CSS tests are complete. The viewport(), page(), and body() methods are all useful for making assertions.

Methods

frame.reset()

Stability: 3 - Stable

Reset the frame's DOM back to the state it was in immediately after you called quixote.createFrame(). You will typically call this before every test.

This method does not re-run scripts. If you need to re-run scripts, use QFrame.reload() instead.

frame.reset()

Example:

beforeEach(function() {
  frame.reset();
});

Note: This method resets the frame size, scroll position, and the <body> element's inner HTML. If you make changes to <head> or <html>, or if you change any <body> attributes (including styles), you will need to reset them manually, or use frame.reload() instead.

frame.reload()

Stability: 3 - Stable

Reload the frame page source and stylesheets completely, as if quixote.createFrame() were called again, but without the overhead of creating the frame.

This method is most useful when integration testing pages that run scripts after load. Because reloading the page is relatively slow, use QFrame.reset() if you don't need re-run the page's scripts.

frame.reload(callback(err))

  • callback(err) (function) Called when the frame has been reloaded.
    • err (Error or null) Any errors that occurred while loading the frame, or null if frame loaded successfully.

Example:

beforeEach(function(done) {
  frame.reload(done);
});

frame.remove()

Stability: 3 - Stable

Remove the test frame entirely. You'll typically call this after all your tests are complete.

frame.remove()

Example:

after(function() {
  frame.remove();
});

frame.get()

Stability: 3 - Stable

Retrieve an element matching a selector. Throws an exception unless exactly one matching element is found. If you don't want the possibility of an exception, use frame.getAll() instead.

element = frame.get(selector, nickname)

  • element (QElement) The element that matches your selector.

  • selector (string) A CSS selector. Any selector that works with document.querySelectorAll() will work. In particular, note that IE 8 is limited to CSS2 selectors only.

  • nickname (optional string) The name to use when describing your element in error messages. Uses the selector by default.

Example: var foo = frame.get("#foo");

frame.getAll()

Stability: 3 - Stable

Retrieve a list of elements matching a selector. If you want to ensure that exactly one element is retrieved, use frame.get() instead.

list = frame.getAll(selector, nickname)

  • list (QElementList) The elements that match your selector.

  • selector (string) A CSS selector. Any selector that works with document.querySelectorAll() will work. In particular, note that IE 8 is limited to CSS2 selectors only.

  • nickname (optional string) The name to use when describing your list in error messages. Uses the selector by default.

Example var fooList = frame.getAll(".foo");

frame.add()

Stability: 3 - Stable

Create an element and append it to the frame's body. Throws an exception unless exactly one element is created. (But that one element may contain children.)

element = frame.add(html, nickname)

  • element (QElement) The element you created.

  • html (string) HTML for your element.

  • nickname (optional string) The name to use when describing your element in error messages. Defaults to the element ID, class names, or tag name, in that order.

Example: var foo = frame.add("<p>foo</p>", "foo");

frame.viewport()

Stability: 3 - Stable

Retrieve the frame's viewport (the part of the page that you can see in the frame, not including scrollbars).

viewport = frame.viewport()

Example: Assert that a banner is displayed at the top of the window and all the way from side to side.

var viewport = frame.viewport();
banner.top.should.equal(viewport.top);
banner.left.should.equal(viewport.left);
banner.width.should.equal(viewport.width);

frame.page()

Stability: 3 - Stable

Retrieve the frame's page (everything you can see or scroll to, not including scrollbars).

page = frame.page()

  • page (QPage) Page properties.

Example: Assert that a sidebar extends the entire height of the page.

var page = frame.page();
sidebar.top.should.equal(page.top);
sidebar.height.should.equal(page.height);

frame.body()

Stability: 3 - Stable

Retrieves the frame's body element.

body = frame.body()

frame.resize()

Stability: 3 - Stable

Changes the size of the frame.

frame.resize(width, height)

  • width (number) The frame's new width
  • height (number) The frame's new height

Compatibility Note: Older versions of Mobile Safari did not strictly obey the width and height attributes on an iframe. Instead, they uses the page width/height or the requested width/height, whichever is larger. You can detect this behavior by using quixote.browser.enlargesFrameToPageSize().

frame.scroll()

Stability: 3 - Stable

Scroll the page so that top-left corner of the frame is as close as possible to an (x, y) coordinate. Note that the page may not scroll at all in some cases, such as when the frame already displays the entire page.

frame.scroll(x, y)

  • x (number) The x coordinate to scroll to.

  • y (number) The y coordinate to scroll to.

Example: frame.scroll(50, 60);

frame.getRawScrollPosition()

Stability: 3 - Stable

Determine the (x, y) coordinate of the top-left corner of the frame. This uses pageXOffset and pageYOffset under the covers. (On IE 8, it uses scrollLeft and scrollTop.)

position = frame.getRawScrollPosition()

  • position (Object) The (x, y) coordinate:
    • x (number) The x coordinate.
    • y (number) The y coordinate.

Compatibility Note: getRawScrollPosition does not attempt to resolve cross-browser differences, with one exception:

  • IE 8 uses scrollLeft and scrollTop rather than pageXOffset and pageYOffset.

frame.forceReflow()

Stability: 3 - Stable

Force the browser to recompute the page layout.

forceReflow()

frame.toDomElement()

Stability: 3 - Stable

Retrieve the underlying HTMLIFrameElement DOM element for the frame.

dom = frame.toDomElement()