ghostjs - Modern web integration test runner
Typical integration test frameworks are a nightmare of callbacks and arbitrary chaining syntax. Ghostjs uses standardized ES7 async functions in order to create a syntax that's extremely easy to reason about and work with. Take a look at our API and an example test case below. Ghostjs currently runs on both Chrome, Firefox (through SlimerJS), and Phantom.
Installation
npm install ghostjs
API
ghost.injectScripts(path)
- Injects scripts into the webpage.ghost.setDriverOpts(opts)
- Sets driver options. You can find a list of supported options here.await ghost.open(url, options={headers={}, settings:{}, viewportSize:{}})
- Instantiates ghostjs and opens a webpageawait ghost.findElement(selector)
- Returns an element instance of this selector.await ghost.findElements(selector)
- Returns an array of element instances that match the given selector.ghost.goBack()
- Navigates back in history one page.ghost.goForward()
- Navigates forward in history one page.await ghost.screenshot(filename?, folder?)
- Saves a screenshot to the screenshots/ folder.await ghost.script(func, [args]?)
- Executes a script within a page and returns the result of that function.await ghost.usePage(string)
- Uses a page as a context to script. E.g., a url from window.open. Pass null to switch back to the main page.await ghost.wait(ms)
- Waits for an arbitrary amount of time. It's typicall better to wait for elements or dom state instead.await ghost.wait(func)
- Waits until the return condition of the passed in function is met. Polls continuously until a return condition is true.await ghost.waitForElement(selector)
- Waits for an element to exist in the page, and returns it.await ghost.waitForElementNotVisible(selector)
- Waits for an element to be hidden or inexistent in the dom.await ghost.waitForElementVisible(selector)
- Waits for an element to exist and be visible on the page.await ghost.waitForPage(string)
- Waits for the a page to be opened opened with the given url (or string search), via window.open.await ghost.waitForPageTitle(string|RegExp)
- Waits for the page title to match the expected value.await ghost.click(selector)
- Clicks on an element specified by the selector, by default in the center of the element.await ghost.fill(selector, text)
- Fills a form field with the provided value. Tries to set the right value for non-text inputs.await element.click(x?, y?)
- Clicks the element, by default in the center of the element.await element.getAttribute(attribute)
- Returns the value of an attribute for this elementawait element.html()
- Returns the innerHTML of an element.await element.file(path)
- Sets a file input to a file on disk.await element.fill(text)
- Sets a form field to the provided value. Tries setting the right value for non-text inputs.await element.isVisible()
- Checks whether or not the element is visible.await element.mouse(type, x?, y?)
- Dispatches a mouse of event of the given type to the element.await element.rect()
- Returns the current coordinates and sizing information of the element.await element.text()
- Returns the textContent of an element.await element.script(func, [args]?)
- Executes a function on the page which receives the DOM element as the first argument.
Usage
Example Test
Waiting for a DOM Condition
await ghostvar hasMoved = await ghostassert
Chaining and promises
// The recommended way to get element text:let el = await ghostlet text = await eltextconsole // If you're looking for something slightly less verbose, you can also chain with .then():let text = await ghostconsole
Dependencies
Chrome
By default ghostjs will use Chrome as a test runner, or when you pass --browser chrome
as a command line argument. You will need to have chrome installed on your machine, but ghostjs will try to automatically locate the binary. You can specify a CHROME_BIN env var to override this location.
You can also set flags that you'd like to specify to the chrome binary by setting the CHROME_FLAGS env variable, separated by commas:
CHROME_FLAGS=--disable-gpu,--force-text-direction=RTL ghostjs --browser chrome test/*.js
PhantomJS
You can choose to test on PhantomJS as a test runner by passing the --browser phantom
option to the ghostjs
command. PhantomJS is installed as a dependency of the ghostjs
package. E.g., you may have the following in your package.json:
"scripts": {
"test": "ghostjs --browser phantom test/*.js"
}
Firefox
You can choose to test on Firefox (through SlimerJS) as a test runner by passing the --browser firefox
option to the ghostjs
command. Firefox must be installed on your computer to run tests against Firefox. E.g., you may have the following in your package.json:
"scripts": {
"test": "ghostjs --browser firefox test/*.js"
}
Note: SlimerJS is not headless and requires a windowing environment to run. If you are trying to run SlimerJS on travis, you can modify your travis.yml to have the following:
before_script: - export DISPLAY=:99.0 - "sh -e /etc/init.d/xvfb start"
You can see how we run both Chrome, Firefox and PhantomJS tests in our example package.json and our .travis.yml
Babel
Since we're using bleeding edge javascript /w async functions we currently recommend that you use babel to run your tests. At a minimum you should install these packages:
npm install babel-preset-es2015 --save-dev
npm install babel-preset-stage-0 --save-dev
In a file named .babelrc
:
{
"presets": ["es2015", "stage-0"]
}
Verbose Logs
You can output verbose website information like console.log statements and errors by using the --verbose
flag. E.g, ghostjs ./test/mytest.js --verbose
.
Slimer JSConsole
The Slimer JSConsole can be very useful when debugging tests. There are two ways to open the console, one inside a test with:
ghost.setDriverOpts({parameters: ['-jsconsole']})
You can also pass an environment variable to enable the console:
GHOST_CONSOLE=1 ./node_modules/.bin/ghostjs
Page Options
onResourceRequested - Pass a custom function to execute whenever a resource is requested.
Network throttling (only in Chrome)
networkOptions: ghost.networkTypes['offline'|'gprs'|'regular2g'|'good2g'|'regular3g'|'good3g'|'regular4g|'dsl'|'wifi']
As of v1.11.0, Ghost supports network throttling for loading pages. This feature is only available when run with the --browser=chrome
flag.
With network throttling, you can simulate running your tests with a variety of connections. These connections are exposed in Ghost under ghost.networkTypes
, and represent the latency, download, and upload speeds that are found in the Chrome devtools.
Contributors
Please see: CONTRIBUTING.md