# Getting Started

When you launch Puppetry the very first time you are expected to see the **welcome page**:

![Puppetry Welcome page](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu70eUl4T7T6M8r8FEX%2F-Lu7PNVoV23XDszCRlBa%2Fgetting-started1.png?alt=media\&token=142314eb-b8eb-440f-bb5c-6dcde4d64547)

At this stage we cannot do much, only to **open** an existing project or **create** one:

![File menu](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu70eUl4T7T6M8r8FEX%2F-Lu7PTSfSQ3L-iqzKMmc%2Fgetting-started2.png?alt=media\&token=c2a5b5e0-5e48-4228-88dc-22e587c1f88f)

Let's create our first project intended to test responsive design on the landing page or our [imaginary ACME forum application](https://docs.puppetry.app/examples).

![New project modal window](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-LhLGXQ01yPwXFYO5zvC%2F-LhLSIYIX6I6xwLOB61S%2Fp-modal-new-project.png?alt=media\&token=85be30e2-a7b1-41e0-925f-bcd1a128e28d)

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](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu70eUl4T7T6M8r8FEX%2F-Lu7Pfsm80G5MIMDY-jl%2Fgetting-started3.png?alt=media\&token=06b6853e-bd22-479a-809e-d02ed45c3355)

Let's add a few targets:

![ACME forum test targets](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu70eUl4T7T6M8r8FEX%2F-Lu7PmOroeD4N1Qy85Nh%2Fgetting-started4.png?alt=media\&token=59ade2ae-60ff-4085-af2e-ddeac82ea139)

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](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu70eUl4T7T6M8r8FEX%2F-Lu7QrkVz-_IyOuo-QYF%2Fscreenshot-1574246866.png?alt=media\&token=c3d67f63-30cf-44ca-8896-03cbdf7214db)

Let's add the first group "Landing page":

![The first test group added](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu70eUl4T7T6M8r8FEX%2F-Lu7Q0jHNZrbAToi2n3h%2Fgetting-started5.png?alt=media\&token=25898f34-8c30-4991-8b2b-b6fea316d0a0)

Under the group record we get a new form to enter test case name. So add one:

![The first test case added](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu70eUl4T7T6M8r8FEX%2F-Lu7Qg759sdAbBjx1zjI%2Fgetting-started6.png?alt=media\&token=58608092-9007-46d2-86fa-4c658845eb1d)

Let's add our first command into the test case. So we click on **Add a command/assertion** button:

![Add a command/assertion button](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-LhLGXQ01yPwXFYO5zvC%2F-LhLWo6WE1L6wSPLnEvj%2Fp-add-command-btn.png?alt=media\&token=484a457b-8d76-4f16-ad94-ebd98c2e2c43)

That brings us to **Edit Command/Assertion** modal window:

![Edit Command/Assertion modal window](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu70eUl4T7T6M8r8FEX%2F-Lu7RsY6mA1Z_NR1TcxZ%2Fgetting-started2.2.png?alt=media\&token=cc6e0b64-d0f5-4b84-92f5-0bc67e15a1c2)

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](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu70eUl4T7T6M8r8FEX%2F-Lu7R8dshbp_-lCqTkTa%2Fgetting-started1.1.png?alt=media\&token=e26803f8-5f3d-45ba-ac78-38df616f6e56)

Many of test steps have additional options collapsed under **Advanced Options** link. E.g:

![Advanced options of page.setViewport command](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu70eUl4T7T6M8r8FEX%2F-Lu7Rl86qbQK6utNj0oG%2Fgetting-started2.1.png?alt=media\&token=e664cae4-5caf-4ff9-8dc6-7072ef447240)

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](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu70eUl4T7T6M8r8FEX%2F-Lu7Rz9ak2VrSSfFWANw%2Fgetting-started3.1.png?alt=media\&token=109e2e58-114b-4050-b93b-cd3395c24bf7)

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](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu70eUl4T7T6M8r8FEX%2F-Lu7SZvra94BVn7XKery%2Fgetting-started3.3.png?alt=media\&token=29b3f264-ce98-47a7-9937-a4e4519365cd)

Next we need `assertVisible` method, so we focus on method input and start typing **"assert"**:

![Searching for a method](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu70eUl4T7T6M8r8FEX%2F-Lu7SU_xVyWUgkUNeCvz%2Fgetting-started4.1.png?alt=media\&token=0b29e24f-21c3-4d7f-9928-9f0d8022db80)

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](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-LuD7r1Evwaq_YbahJqO%2F-LuDGagP9kldDwzU_fwq%2Fassert-visible.png?alt=media\&token=4af03e4d-8e01-42a7-935b-ff5c945876a4)

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](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu70eUl4T7T6M8r8FEX%2F-Lu7TWj9U5Qa5Eu6Qc_g%2Fgetting-started7.png?alt=media\&token=5c4bc539-1c7e-4aef-8297-a4e4b07eece7)

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](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu70eUl4T7T6M8r8FEX%2F-Lu7TyhYX6I_w10iRXNC%2Fgetting-started6.1.png?alt=media\&token=b74c7b37-e893-4d26-983c-3d1e4530aced)

Here we just click on **Run** button. 

As we run it Puppetry opens panel **Test report** with test results:

![Test results](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu70eUl4T7T6M8r8FEX%2F-Lu7V757Al7V3ZN41pLo%2Fscreenshot-1574248046.png?alt=media\&token=66f847a3-40a9-46d8-b84c-c07dd3e699af)

It says everything is fine. If we click on the screenshot thumbnail it gets open in the viewer.

![Screenshot in the viewer](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu70eUl4T7T6M8r8FEX%2F-Lu7WB93_s2z-LfdlzDZ%2Fgetting-started-img.png?alt=media\&token=afaf1371-1328-42a9-9d77-59d1b586bd6d)

Alternatively we can click on **Download** link, which appears when we hover the thumbnail.

![Download screenshot](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu70eUl4T7T6M8r8FEX%2F-Lu7Uz5-g6T5_CnaCKFl%2Fgetting-started9.png?alt=media\&token=2a7e5bbd-9933-48b9-be13-808bc7137ce3)

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](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu70eUl4T7T6M8r8FEX%2F-Lu7XMFivL8LFh4DXn8m%2Fgetting-started7.1.png?alt=media\&token=cf32f207-177a-4bb0-9bc8-f65b00eb3972)

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](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu70eUl4T7T6M8r8FEX%2F-Lu7YDoMiXWT8S9JzYwU%2Fgetting-started11.png?alt=media\&token=5eee9dac-9402-4010-b6e0-18534e35d573)

Then right-click on the selection and pick the **Copy** option in the context-menu.

![Copying the selection](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu70eUl4T7T6M8r8FEX%2F-Lu7YSL5JZNhuCHt1MIm%2Fgetting-started12.png?alt=media\&token=a724df1d-b8a3-4917-bf9c-6e1d916cf037)

Now we focus the destination - `page.emulate` command of the second test case and right-click again:

![Pasting the selection](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu70eUl4T7T6M8r8FEX%2F-Lu7YoXjmfd9O8K_RSwj%2Fgetting-started13.png?alt=media\&token=6f22b725-fcc6-48f6-9320-e3b7f75f4222)

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](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu70eUl4T7T6M8r8FEX%2F-Lu7ZjM-f4Tuy9DjheH4%2Fgetting-started14.png?alt=media\&token=44635237-c6c5-4caa-8b3b-c7d18cfea656)

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](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu70eUl4T7T6M8r8FEX%2F-Lu7_8uCljcuoi_y6Q0p%2Fgetting-started8.1.png?alt=media\&token=cbd5d655-5cd2-422a-92d7-0e4c43c03d86)

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](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu70eUl4T7T6M8r8FEX%2F-Lu7_KqdtxxdILMn8kmp%2Fgetting-started9.1.png?alt=media\&token=8a0cad40-1cf6-4c1a-9612-2c2fbc33362d)