Browsing

Quick start

First of all, you need a instance of Ghost web client:

from ghost import Ghost
ghost = Ghost()

Open a web page

Ghost provide a method that open web page the following way:

page, ressources = ghost.open('http://my.web.page')

This method returns a tuple of main ressource (web page) and all loaded ressources (such as CSS files, javascripts, images...).

All those ressources are backed as HttpRessource objects.

At the moment HttpRessource objects provide the following attributes:

url: The ressource url.
http_status: The HTTP response status code.
headers: The response headers as a dict.

Execute javascript

Executing javascripts inside webkit frame is one of the most interesting features provided by Ghost:

result, ressources = ghost.evaluate(
    "document.getElementById('my-input').getAttribute('value');")

The return value is a tuple of:

last javascript last statement result.
loaded ressources (e.g.: when an XHR is fired up).

As many other Ghost methods, you can pass an extra parameter that tells Ghost you expect a page loading:

page, ressources = ghost.evaluate(
    "document.getElementById('link').click();", expect_loading=True)

Then the result tuple wil be the same as the one returned by Ghost.open().

Play with forms

Fill a field

You can set a form field value trougth Ghost.set_field_value(selector, value, blur=True, expect_loading=False):

result, ressources = ghost.set_field_value("input[name=username]", "jeanphix")

If you set optional parameter `blur` to False, the focus will be left on the field (usefull for autocomplete tests).

For filling file input field, simply pass file path as `value`.

Fill an entire form

You can fill entire form trougth Ghost.fill(selector, values, expect_loading=False):

result, ressources = ghost.fill("form", {
    "username": "jeanphix",
    "password": "mypassword"
})

Submit the form

Yon can submit the form by firing `submit` event:

page, ressources = ghost.fire_on("form", "submit", expect_loading=True)

Waiters

Ghost provides several methods for waiting for specific things before the script continue execution:

wait_for_alert()

That wait until a javascript alert() is send.

result, ressources = ghost.wait_for_alert()

wait_for_page_loaded()

That wait until a new page is loaded.

page, ressources = ghost.wait_for_page_loaded()

wait_for_selector(selector)

That wait until a element match the given selector.

result, ressources = ghost.wait_for_selector("ul.results")

wait_for_text(text)

That wait until the given text exists inside the frame.

result, ressources = ghost.wait_for_selector("My result")

Confirm

Accept or deny javascript confirm is quite easy:

with Ghost.confirm():
    # The confirm() box fired up by click will be accepted
    self.ghost.click('#confirm-button')

with Ghost.confirm(False):
    # The confirm() box fired up by click will be denied
    self.ghost.click('#confirm-button')

Prompt

Filling a value in prompt box:

with Ghost.prompt('my value'):
    # prompt() box fired up by click will be filled with 'my value'
    self.ghost.click('#prompt-button')

Capture viewport

Ghost.capture_to(path, region=None, selector=None) method let's you take webkit current frame screenshots.

If you need to capture a specific region of the viewport, just provide a selector (or coordinates tuple) that feets your needs:

ghost.capture_to('header.png', selector="header")

Test client

WSGI apps

Requirements:

pip install tornado

ghost.py provides a simple GhostTestCase that deals with WSGI applications:

import unittest
from flask import Flask
from ghost import GhostTestCase


app = Flask(__name__)

@app.route('/')
def home():
    return 'hello world'


class MyTest(GhostTestCase):
    port = 5000

    app = app

    def test_open_home(self):
        self.ghost.open("http://localhost:%s/" % self.port)
        self.assertEqual(self.ghost.content, 'hello world')


if __name__ == '__main__':
    unittest.main()

Debug your test

Tests can be run with a UI by setting display class member to True:

class MyTest(GhostTestCase):
    display = True

Sample use case

The following test tries to center http://www.openstreetmap.org/ map to France:

# Opens the web page
ghost.open('http://www.openstreetmap.org/')
# Waits for form search field
ghost.wait_for_selector('input[name=query]')
# Fills the form
ghost.fill("#search_form", {'query': 'France'})
# Submits the form
ghost.fire_on("#search_form", "submit")
# Waits for results (an XHR has been called here)
ghost.wait_for_selector(
    '#search_osm_nominatim .search_results_entry a')
# Clicks first result link
ghost.click(
    '#search_osm_nominatim .search_results_entry:first-child a')
# Checks if map has moved to expected latitude
lat, ressources = ghost.evaluate("map.center.lat")
assert float(lat.toString()) == 5860090.806537