Getting Started

When you launch Puppetry the very first time you are expected to see the welcome page:
Puppetry Welcome page
At this stage we cannot do much, only to open an existing project or create one:
File menu
Let's create our first project intended to test responsive design on the landing page or our imaginary ACME forum application.
New project modal window
So we enter project name, browse for location and provide a name for the first suite. After pressing submit we end up on the suite page:
Newly created suite
Let's add a few targets:
ACME forum test targets
Here we identify main menu container, which is visible on desktop, but behind the burger menu on mobile. We define teaser target (the first matching the selector), which also visible only on desktop. Eventually we specify mobile menu container that on the contrary shows up on mobile, but hidden on desktop.
Now we switch to the Test Cases tab:
No test cases so far
Let's add the first group "Landing page":
The first test group added
Under the group record we get a new form to enter test case name. So add one:
The first test case added
Let's add our first command into the test case. So we click on Add a command/assertion button:
Add a command/assertion button
That brings us to Edit Command/Assertion modal window:
Edit Command/Assertion modal window
Our goal is to ensure desktop-like screen size. So we select page target and setViewport method. We set screen width 1440 and height 900:
Adding command to set viewport
Many of test steps have additional options collapsed under Advanced Options link. E.g:
Advanced options of page.setViewport command
Here we don't need to change them. We click on Save button and get back to test case editing, where we click on Add a command/assertion button again to set navigation URL:
Adding command to visit forum landing page
Now we have to assert that desktop menu and teasers are visible in this test case, but mobile menu not. So we click Add a command/assertion button and select a target identifier corresponding to mobile menu container:
Selecting a target
Next we need assertVisible method, so we focus on method input and start typing "assert":
Searching for a method
The list of options adjust according to search keyword, so we can easily find the required method.
Asserting MENU_DESKTOP_CONTAINER target is available and visible
We take "available on the page and observable" option in the select "The target is". This means the element available in page DOM and can be visually located. We save the changes. Similarly we create assertions for desktop menu and teaser, but take option "available, but NOT observable". Finally we add command page.screenshot and our first test case is ready:
Test case of RWD on landing page for 1440x900 display
I would suggest now to run the tests and check if everything is ok. So we press F6 and get the following modal window:
Run Tests modal window
Here we just click on Run button.
As we run it Puppetry opens panel Test report with test results:
Test results
It says everything is fine. If we click on the screenshot thumbnail it gets open in the viewer.
Screenshot in the viewer
Alternatively we can click on Download link, which appears when we hover the thumbnail.
Download screenshot
Then the screenshot will be open with default viewer in your hosting OS.
Let's now go further and create a new test case named on iPhone 8 mobile menu displayed. We start it with the command to emulate iPhone 8 device:
Adding command to emulate iPhone 8
Next we need a command to visit the landing page and assertions from the previous case. Let's just copy/paste them. We click on the every command with Shift pressed to select records.
Selecting records for a bulk action
Then right-click on the selection and pick the Copy option in the context-menu.
Copying the selection
Now we focus the destination - page.emulate command of the second test case and right-click again:
Pasting the selection
We have just copied, bu the are still addressing the desktop view and need to be adjusted for iPhone device. But let's see what happens if we run the tests with failing assertions. So we press F6 and observer the test report:
Test report with failing assertion
So you see it warns us about the failure and provides detailed information why the assertion failed.
If we switch to suite tab (rwd.json) we see that failed assertion record is highlighted:
Failing assertion gets highlighted
When working with test cases (especially debugging) sometimes you will want to temporarily disable some test steps and run only the ones you currently focused on. That can be done from the context menu (right-click). The disabled test steps will be also highlighted:
Disabled test steps are highlighted