# Getting Started

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

![Puppetry welcome page](https://2843146877-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-LhLGXQ01yPwXFYO5zvC%2F-LhLRcLvns3uBICacvQ_%2Fp-welcome-screen.png?alt=media\&token=e083e991-ba4f-4f97-abff-5c9e24ea01d7)

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

![File menu options](https://2843146877-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-LhLGXQ01yPwXFYO5zvC%2F-LhLRkNqJxTAoBr6oiD3%2Fp-new-file-menu.png?alt=media\&token=b7ec37ab-8dd0-431a-8248-4d005a216efb)

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://2843146877-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://2843146877-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-LhtIcbFlIQcPdlV7b_m%2F-LhtIwDBGihw2qETiJVv%2Fnewly-created-suite.png?alt=media\&token=17f6606d-a35f-41f7-9647-7e5e3c716747)

Let's add a few targets:

![ACME forum test targets](https://2843146877-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-LhtIcbFlIQcPdlV7b_m%2F-LhtIz5e300-kQM1MrX0%2Frwd-suite-targets.png?alt=media\&token=23089026-767a-408b-83c9-98e046ee7461)

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:

![Initially no groups in the suite](https://2843146877-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-LhtIcbFlIQcPdlV7b_m%2F-LhtJ1rpwwy4DmKd2bLx%2Finitially-no-groups.png?alt=media\&token=51d06967-b8d2-419a-ae57-d6044555fc5d)

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

![Expanding the first group](https://2843146877-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lhtbt5ldQrH6yaioH4v%2F-Lhtc5acajFjV3hs3oGg%2Ffirst-group.png?alt=media\&token=cf4ab4b5-deae-4c3c-bb2a-d109d2ea36df)

Now we have to expand the newly added group, so we click **expand** button:

![Expand button](https://2843146877-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-LhLGXQ01yPwXFYO5zvC%2F-LhLVc6ZgPkr6wECB-1b%2Fp-expand-group.png?alt=media\&token=95f3c268-fcf7-43ff-9acd-9c1a72ba8465)

Under the group record we get a new form to enter test case name:

![Empty test case expanded](https://2843146877-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lhtbt5ldQrH6yaioH4v%2F-LhtcG31HcPLTNK6OJ8L%2Fcreating-the-first-test-case.png?alt=media\&token=a1b77aad-4705-4bc4-81d7-9e670ff7be32)

As a new test case record appears we again click **expand** button next to it:

![](https://2843146877-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lhtbt5ldQrH6yaioH4v%2F-LhtcJfs_JPqxgqVv0VI%2Fempty-test-case-expanded.png?alt=media\&token=1ba3c587-9cd9-4ba6-a235-5f250e4f05e3)

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://2843146877-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://2843146877-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-LhLX26Gvdcoia5xm1wb%2F-LhLXHTZTTlVFXGl61H8%2Fp-edit-command-empty.png?alt=media\&token=80d7fd2a-f4fc-472e-b57c-64af908c25f9)

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**:

![](https://2843146877-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-LhLX26Gvdcoia5xm1wb%2F-LhLXtTY9Lonhs0huJqj%2Fp-page-viewport.png?alt=media\&token=c0eaac5e-5c1c-467a-964d-2a8149714630)

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

![Advanced options of page.setViewport command](https://2843146877-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-LhLX26Gvdcoia5xm1wb%2F-LhLYMoPwuSFKtG7QbgC%2Fp-viewport-options.png?alt=media\&token=bee369af-c83e-402e-8f57-1cdf23b86c46)

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:

![page.goto command](https://2843146877-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-LhLX26Gvdcoia5xm1wb%2F-LhLZ4BxSdefOxHu1iv-%2Fp-goto.png?alt=media\&token=b8a94755-44ba-464f-960c-1c48bce951b6)

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://2843146877-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-LhLX26Gvdcoia5xm1wb%2F-LhLZlfejF735wUtkcxq%2Fp-select-target.png?alt=media\&token=20fbfc48-22b1-416b-9a7f-ef0791db31f5)

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

![Searching for a method](https://2843146877-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-LhLX26Gvdcoia5xm1wb%2F-LhL_72jnCipuK8eBBew%2Fp-search-select.png?alt=media\&token=59b01098-6784-4e91-9803-8383fe408eb1)

The list of options adjust according to search keyword, so we can easily find the required method.

![TARGET.assertVisible method](https://2843146877-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-LhLX26Gvdcoia5xm1wb%2F-LhL_VBMDlxtOLBsE1au%2Fp-is-visible.png?alt=media\&token=602accf5-1dae-4a02-8b79-1ffe59fcb41c)

We tick off **value** checkbox and click **Save** button. Similarly we create assertions for desktop menu and teaser, but set **value** to on. Finally we add command `page.screenshot` and our first test case is ready:

![](https://2843146877-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lhtbt5ldQrH6yaioH4v%2F-LhtcMr8qNKXXRvi-yck%2Ffirst-test-case.png?alt=media\&token=da4c14de-38a6-4ed6-bda0-d19fed85e829)

I would suggest now to run the tests and check if everything is ok. So we press **F6** and get the following modal window:

![Test Reports modal window](https://2843146877-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-LhLX26Gvdcoia5xm1wb%2F-LhLavDqTBSCQabPH03Z%2Fp-run-test-modal.png?alt=media\&token=631041ac-89c5-4d6c-9475-3199db6e0731)

Here we just click on **Run** button. Yet the available options are:

* **On/Off** switch makes Puppetry to run the test either in headless mode or in default browser (additional options will open as son as you set it **On**)
* select a [target environment](https://docs.puppetry.app/template)
* select which suites we include in the run

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

![Test results](https://2843146877-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-LhLe3x0LuRGU_qC2O-F%2F-LhLfHJTpDJVhmQ0b05o%2Fp-test-report.png?alt=media\&token=66eb0c7d-6219-4ba7-b5ff-23819309ac9d)

It says everything is fine. If we click on Open directory with generated screenshots link we can see generated folder named after the test case where we can find the screenshot:

![Generated screenshot](https://2843146877-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-LhLe3x0LuRGU_qC2O-F%2F-LhLfspmHAqA5yqYGgzv%2Fp-screenshot-folder.png?alt=media\&token=e62abdd2-a4a2-4ddd-9ba5-708d81be1ef1)

Now we create a new test case named **on iPhone 8 mobile menu displayed**. First we add a command to emulate iPhone 8 device:

![page.emulate command](https://2843146877-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-LhLe3x0LuRGU_qC2O-F%2F-LhLglDX5mtsNBiSefA3%2Fp-emulate-device.png?alt=media\&token=912e1148-275d-4419-bca0-e98f5ed1bfc5)

Next we need a command to visit the landing page and assertions from the previous case. Let's just copy/paste them. So we focus on `page.goto` command of the first test case and right-click on it:

![Copying page.goto command](https://2843146877-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-LhLe3x0LuRGU_qC2O-F%2F-LhLhDyBa121M8iVuvbk%2Fp-copy-goto.png?alt=media\&token=b10680ed-2bf0-48a5-ad2b-f777b479d5be)

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

![Insert copied command](https://2843146877-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-LhLe3x0LuRGU_qC2O-F%2F-LhLhf1H_U7qh6VbQRzB%2Fp-paste-goto.png?alt=media\&token=dfbea2a4-2e23-4486-ab7a-feb6f620e9d2)

We need to repeat it for the assertions and `page.screenshot` command. Then we edit assertions for opposite values and give a new title for `page.screenshot`. After that our first suite is complete.

But what if any of assertion was wrong? Let's deliberately change assertion value for mobile menu container in the second case. So now it's expected to be not visible. We run tests (**F6**) and observer the failed test step reported:

![Failed test](https://2843146877-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-LhLe3x0LuRGU_qC2O-F%2F-LhLipgs8_ZqP6weJrv8%2Fp-error-report.png?alt=media\&token=17a42a36-9514-46b6-8403-8d6594f817df)

If we switch to suite tab (rwd.json) we see that failed assertion record is highlighted:

![Failed assertion is highlighted](https://2843146877-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-LhLe3x0LuRGU_qC2O-F%2F-LhLjAYzoTTx6r1mRR1M%2Fp-errored-state.png?alt=media\&token=0b1e7ef6-c389-498c-8733-6bd675a921de)

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://2843146877-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-LhLe3x0LuRGU_qC2O-F%2F-LhLk3wy9igbDDZfy-Lr%2Fp-disabeld-state.png?alt=media\&token=b907e7a5-fc4a-4db2-9b53-bbb8c4d33b92)