Isomorfeus Puppetmaster

A framework for acceptance tests or simply running tests in a headless browser. Allows for writing javascript browser tests in pure ruby. It is tailored for Isomorfeus and using puppeteer-ruby

Community and Support

At the Isomorfeus Framework Project

Installation

In Gemfile: gem 'isomorfeus-puppetmaster', then bundle install

Configuration

Chrome is the default browser used.

Iodine is the default rack server, automatically configured.

Getting the app ready and running:

  1. Assign a rack app
  2. Boot the app

For Example:

Isomorfeus::Puppetmaster.app = TestApp
Isomorfeus::Puppetmaster.boot_app

Include the Puppetmaster DSL in the spec_helper.rb:

RSpec.configure do |config|
  config.include Isomorfeus::Puppetmaster::DSL
end

Ready to play!

Terminology

There are Browsers which may have windows or tabs, which translate to targets or pages which may contain documents or frames which consist of elements or elements. In Puppetmaster, which is focusing on headless testing, the main "thing" is just a page. Its possible to open many pages at once. A document consists of elements. Simply working with just pages, documents and elements makes testing a lot simpler.

Basic usage pattern

  1. Find something
  2. Interact with it

Sessions

Using visit will open a default session. However, additional browser sessions may be opened with:

s = new_session() # additional args may be passed, like headless: false, devtools: true
# now the session can be interacted with:
s.visit('/')
t = new_session() # multiple sessions may be active at the same time
t.visit('/')

Pages

A page is a Puppeteer::Page and provides its complete API plus some additional convenience methods. The drivers opens a empty default page, to use that and go to the apps root page:

page = visit('/')

This provides the page page which can further be used to interact with. To go to another location, call visit or goto on that doc:

page.visit('/login') # or
page.goto('/login')

To open another page:

page2 = new_page('/play')

Both open pages can then be independently interacted with:

page.visit('/go')
page2.goto('/location')

For debugging:

page = visit('/', headless: false, devtools: true)

This will close the current browser if the options for headless and devtools dont match, and open a new one with the supplied headless and devtools options.

Pages and Ruby

Ruby can be executed within pages by simply providing a block or a string:

page.eval_ruby do
  $document['my_id'].class_names
end

# or

page.eval_ruby "$document['my_id'].class_names"

Pages and Javascript

Javascript can be be evaluated within pages by simply providing a string:

page.eval '1+1' # => 2

Elements

Finding Elements ...

Elements can be found by CSS selectors or XPath queries. Element can be found from the page or or other elements as root.

... with CSS selectors

Pages and elements provide methods for finding single elements or a group of elements with CSS selectors. Examples: Find a single element in a page:

element1 = page.find('div') # finds the first div in the page
element2 = page.find('#super') # find element with id="super"

Find a single element from another element:

element3 = element1.find('div') # find first div within the element

Find multiple elements in a page or from a element:

element_array1 = page.find_all('div') # finds all div's in a page
element_array2 = element2.find_all('div') # find all div's within element2

... with XPath queries

Pages and elements provide methods for finding single elements or a group of elements with XPath queries. Examples: Find a single element in a page:

element1 = page.find_xpath('//div') # finds the first div in the page
element2 = page.find_xpath("//div[contains(@id,'super')]") # find div with id="super"

Find a single element from another element:

element3 = element1.find_xpath('//div') # find first div within the element

Find multiple elements in a page or from a element:

element_array1 = page.find_all_xpath('//div') # finds all div's in a page
element_array2 = element2.find_all_xpath('//div') # find all div's within element2

Interacting with elements

Puppetmaster provides methods for emulating user interactions with elements or pages.

Mouse

element1.click

Keyboard

element4 = page.find('input')
element4.type_text('Message')

Tests

To run tests:

  • clone repo
  • bundle install
  • bundle exec rake

Usage examples

There are a lot of usage examples in the spec directory of the repo, see https://github.com/isomorfeus/isomorfeus-puppetmaster/tree/master/spec/common.