is a webkit web client written in python.

from ghost import Ghost ghost = Ghost() page, extra_resources ="") assert page.http_status==200 and 'jeanphix' in ghost.content


First you need to install either PyQt or PySide that are availables for many platforms.

Then you may install using pip:

pip install


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, resources ='')

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

All those resources are backed as HttpResource objects.

At the moment Httpresource objects provide the following attributes:

Execute javascript

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

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

The return value is a tuple of:

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

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

Then the result tuple wil be the same as the one returned by

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, resources = 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, resources = ghost.fill("form", { "username": "jeanphix", "password": "mypassword" })

Submit the form

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

page, resources ="form", "submit", expect_loading=True)


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


That wait until a javascript alert() is send.

result, resources = ghost.wait_for_alert()


That wait until a new page is loaded.

page, resources = ghost.wait_for_page_loaded()


That wait until a element match the given selector.

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


That wait until the given text exists inside the frame.

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


Accept or deny javascript confirm is quite easy:

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


Filling a value in prompt box:

with Ghost.prompt('my value'): # prompt() box fired up by click will be filled with 'my value''#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


pip install flask 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 @classmethod def create_app(cls): return app def test_open_home(self):"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 map to France:

# Opens the web page'') # Waits for form search field ghost.wait_for_selector('input[name=query]') # Fills the form ghost.fill("#search_form", {'query': 'France'}) # Submits the form"#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 '#search_osm_nominatim .search_results_entry:first-child a') # Checks if map has moved to expected latitude lat, resources = ghost.evaluate("") assert float(lat.toString()) == 5860090.806537


Ghost provides an extension for django built on to of the upcoming LiveServerTestCase.

from ghost.ext.django.test import GhostTestCase