# Page Commands

## page.emulate

Emulates given device metrics and user agent

![page.emulate](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu8cVABrI3lmtDZ78eI%2F-Lu8fFnw4GUu5cTsWWGu%2Fpage.emulate.png?alt=media\&token=d265bdb6-a222-4d0b-b154-d8d1b8e32284)

## page.setViewport

Defines browser viewport, where the viewport is the user's visible area of a web page

![page.setViewport ](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu8cVABrI3lmtDZ78eI%2F-Lu8fPgzEpu6CSDgo9wn%2Fpage.setViewport.png?alt=media\&token=f579aa90-ee3d-4841-98e5-336d0a12073d)

![page.setViewport predefined resolution list](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu8cVABrI3lmtDZ78eI%2F-Lu8f_DZsmrk8QfgewFZ%2Fpage.setViewport2.png?alt=media\&token=b0481490-3203-4945-a1ed-843a7b817522)

![page.setViewport advanced options](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu8cVABrI3lmtDZ78eI%2F-Lu8fjBZbmRRPoGh_6ZH%2Fpage.setViewport3.png?alt=media\&token=5d64c851-0fa0-4152-ab40-acaf89d5092f)

## page.goto

Navigates to a given URL and waits until the page loaded

![page.goto](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu8cVABrI3lmtDZ78eI%2F-Lu8fs7Ybf29GhI2WqjO%2Fpage.goto.png?alt=media\&token=4ba13f8d-1377-4d58-ab72-d1d404117c3c)

## page.screenshot

Makes a screenshot of the page

![page.screenshot](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu8cVABrI3lmtDZ78eI%2F-Lu8g8Jj8tOCq-ObBPcr%2Fpage.screenshot.png?alt=media\&token=f76d3dd7-d511-4a30-a12e-1656a2ecf82c)

![We can select targets to be highlighted on the screenshot](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu8cVABrI3lmtDZ78eI%2F-Lu8gE98NizazsQ9v6er%2Fpage.screenshot2.png?alt=media\&token=d9e96186-3b0d-4a61-89d2-af97fed0a7dd)

![page.screenshot advanced options](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu8cVABrI3lmtDZ78eI%2F-Lu8gQC_UOCmAwMAiv1v%2Fpage.screenshot3.png?alt=media\&token=dad4e31c-1ab9-4e35-9cb9-071fdde7d41a)

## page.click

Emulates mouse click according to given options

![page.click](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu8o8YObuzbk53qxOmH%2F-LuCC6wwEsIahnyZ45EW%2Fpage.click.png?alt=media\&token=1ed4a3ce-a1a1-47f6-b114-07318229cfd7)

## page.moveMouse

Moves mouse to given position

![page.moveMouse](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu8o8YObuzbk53qxOmH%2F-LuCCOoBPNhP_QkevffY%2Fpage.moveMouse.png?alt=media\&token=a6236e62-91ae-457a-ac8d-fe10b1507704)

## page.tap

Emulates tap according to given options

![page.tap](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu8o8YObuzbk53qxOmH%2F-LuCCWfQ0swFDH8-lxZl%2Fpage.tap.png?alt=media\&token=edfcec5c-8b60-4099-afec-015f0cbd100e)

## page.press

Emulates pressing on a key, optionally with modifiers such as ⇧, ⌥, alt, control, ⌘

![page.press](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu8o8YObuzbk53qxOmH%2F-LuCCc-EY2Rmwlv2_ujA%2Fpage.press.png?alt=media\&token=af549b9a-2a97-4458-b053-4e412f78c467)

![page.press advanced options](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu8o8YObuzbk53qxOmH%2F-LuCChdqq_YineGW4_h6%2Fpage.press2.png?alt=media\&token=acf352c4-3eb6-4aa5-a115-4c394e6ff108)

## page.scroll

Scrolls the document in the window by the given amount

![page.scroll](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu8o8YObuzbk53qxOmH%2F-LuCCnztEj6w04nNveJF%2Fpage.scroll.png?alt=media\&token=49be04aa-d820-4b14-9097-3e511c579437)

## page.reload

Refreshes the page

![page.reload](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu8o8YObuzbk53qxOmH%2F-LuCCuCcbtHBpjlIGvoc%2Fpage.reload.png?alt=media\&token=11cc86f5-afc4-482e-ad05-05598f963735)

## page.setUserAgent

Sets custom user agent

![page.setUserAgent](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu8o8YObuzbk53qxOmH%2F-LuCDAYIjOaMpcP5BxLF%2Fpage.setUserAgent.png?alt=media\&token=3cf4a732-5a5f-4c45-aa76-647cc8461842)

{% hint style="info" %}
While running test on < 3.0.1 this method requires adding "--no-sandbox --disable-setuid-sandbox" Chromium arguments in Browser options
{% endhint %}

## page.setCookie

Sets cookies on the page

![page.setCookie](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu8o8YObuzbk53qxOmH%2F-LuCDGxoAtV7rYvTzCdv%2Fpage.setCookie.png?alt=media\&token=1a9fec78-e362-4d57-9254-3bfefbb1e3e8)

![page.setCookie advanced options](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu8o8YObuzbk53qxOmH%2F-LuCDioSXax-hG7-WnnY%2Fpage.setCookie2.png?alt=media\&token=542defc7-3de5-448a-bb5c-972f8732b5d0)

## page.mockRequest

Intercepts to a given URL and replaces it according to provided data

{% hint style="info" %}
As soon as a matching request intercepted the session gets detached, meaning Puppetry stop listening for mocking. You have to set `page.mockRequest` before every request that you want to mock.
{% endhint %}

![page.mockRequest](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-LvtxgAhETqncmwcBlSP%2F-LvtyJHoKFtqBJVjnPy5%2Fmock-request2.png?alt=media\&token=ce780ce7-f35c-4b18-b2a7-d63c689915e0)

## page.waitFor

Waits for a given time before proceeding to the next command

![page.waitFor](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu8o8YObuzbk53qxOmH%2F-LuCDd1lTcqk9fkmc6pe%2Fpage.waitFor.png?alt=media\&token=4d943022-3801-47ba-8f97-8474e2d85c3c)

## page.waitForSelector

Waits for an element matching a provided [CSS selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors)

![page.waitForSelector](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu8o8YObuzbk53qxOmH%2F-LuCDs1fv7-zegrBi3DS%2Fpage.waitForSelector.png?alt=media\&token=26ee6560-55c2-4e9b-ab6d-2ab5d864e37d)

## page.waitForNavigation

Waits until a given event before proceeding to the next command

![page.waitForNavigation](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu8o8YObuzbk53qxOmH%2F-LuCE1J9Ym4DZzx86lL2%2Fpage.waitForNavigation.png?alt=media\&token=4dd32eb2-3cd7-408a-8495-5d00c6f148fc)

## page.waitForResponse

Waits for HTTP(S) response

![page.waitForResponse](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu8o8YObuzbk53qxOmH%2F-LuCER0JxgMiT3lbpaE3%2Fpage.waitForResponse.png?alt=media\&token=45f5b9de-835a-4441-a0ec-a1d62e924683)

## page.waitForRequest

Waits for HTTP(S) request

![page.waitForRequest](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu8o8YObuzbk53qxOmH%2F-LuCEYonVGMtm6B0U-8h%2Fpage.waitForRequest.png?alt=media\&token=e7bf8ae9-aa21-488b-b89b-c93f58544fcd)

## page.authenticate

Provide credentials for [HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication).

![page.authenticate](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-M8KlMFo7vbnnuw-3be4%2F-M8Kor_IRzIPL3erZ5IG%2Fpage.authorize.png?alt=media\&token=d0314300-ce16-4764-bfbb-bb3dfb615893)

## page.evaluate

Evaluates JavaScript code in the page context

![page.evaluate](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu8o8YObuzbk53qxOmH%2F-LuCEfY6r8qhpV_y2HC_%2Fpage.evaluate.png?alt=media\&token=a26798c9-408f-4351-8952-71641d548373)

## page.runjs

Runs custom JavaScript code in the test suite with use of [Puppeteer API](https://pptr.dev) and [Puppetry API](https://docs.puppetry.app/command-api). You can access [dynamic environment variables](https://docs.puppetry.app/template) via `ENV` map (e.g. `ENV[VAR_NAME]`)

![page.runjs](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu8o8YObuzbk53qxOmH%2F-LuCEmdN5f8jOPzemzvG%2Fpage.runjs.png?alt=media\&token=ab65d134-f74c-497f-9abf-0bed079879fc)

## page.debug

Stops execution of JavaScript, and calls (if available) the [debugging function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/debugger). During test scenarios may happen many things - DOM changes, pages load. It makes hard to figure out why some test assertions fail in some particular moment. You can use this tool to set a breakpoint. Test flow will stop as soon as it reaches this point. So you will be able to examine the page state with DevTools.

![page.debug](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu8o8YObuzbk53qxOmH%2F-LuCEraz5HGj7Bm8OpG6%2Fpage.debug.png?alt=media\&token=b9116175-677d-4e69-aa73-17bf632b7403)

## page.closeDialog

Listen to dialog events and dismiss or accept dialogs (alert, beforeunload, confirm or prompt) as they are called

> The step must be defined before the expected dialog event

![page.closeDialog](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-Lu8o8YObuzbk53qxOmH%2F-LuCFFm_t_PoM_rdoQD1%2Fpage.closeDialog.png?alt=media\&token=44e74095-c85c-47e4-81db-3dc85b68907d)

## page.assignVar

Assigns template variable dynamically

![page.assignVar](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-LuCFLCgDcmFx-IucPHY%2F-LuCFPpPXb2sl8iy1ePK%2Fpage.assignVar.png?alt=media\&token=520810a9-82b0-4446-a4a5-2b2386403d00)

## page.assignVarRemotely

Polls `URL` with a given intervals until a response satisfying `parserFn` function received or a specified timeout exceeded. It can be used, for example, to retrieve a value from an [email sent by the application under test](https://docs.puppetry.app/testing-emails)

![page.assignVarRemotely](https://3461068122-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdyKJ-zzeS2hB7DF04J%2F-LuCFLCgDcmFx-IucPHY%2F-LuCFUKgHJAQBs1BcZvQ%2Fpage.assignVarRemotely.png?alt=media\&token=2b9e6d2f-d7dc-42e6-b222-dff993f92190)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.puppetry.app/test-step/commands.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.