# Command API

## NPM modules

Modules "fs", "path" and "os" exposed with the corresponding variables.

```javascript
const title = ( await bs.page.title() ) + os.version();
```

{% hint style="info" %}
Available since ver. 3.2.6
{% endhint %}

## Puppeteer methods

* **bs** - object representing browsing session
  * **browser** - instance of [Browser](https://pptr.dev/#?product=Puppeteer\&version=v1.15.0\&show=api-class-browser), which is being created in test `setup` with configuration provided in Puppetry app
  * **page** - instance of [Page](https://pptr.dev/#?product=Puppeteer\&version=v1.15.0\&show=api-class-page) (alias of `bs.browser.page`)
  * **performance**
    * **resources** - array with network activity logs
  * **getGaTracking** - log of Google Analytics beacons
  * **getTarget** - get target by name
  * **getTargetOrFalse** - the same as previous, but when target is not available in the DOM return false instead of throwing exception
  * **target(**`element: ElementHandle`**)** - helpers 
    * `getProp(prop: string): Promise<string>` - obtain element property value
    * `getAttr(attr: string): Promise<string>` -  obtain element attribute value
    * `isVisible(): Promise<boolean>` - find out f element visible
    * `select(value: string): Promise<void>` - set a value on select element

Examples:

```javascript
// Navigating to "https://dsheiko.github.io/react-html5-form/"
  await bs.page.goto( "https://dsheiko.github.io/react-html5-form/", {
    timeout: 30000,
    waitUntil: "load"
  });
  
  const title = await bs.page.title();
```

### Working with targets

Assuming we have targets `SUBMIT_BTN`, `EMAIL_INPUT` defined with Puppetry app

```javascript
// Emulating mouse click
await ( await bs.getTarget( "SUBMIT_BTN" ) ).click();   
// Emulating user input
await ( await bs.getTarget( "EMAIL_INPUT" ) ).type( "json@snow.got" );
// Obtaining "name" attribute's value of EMAIL_INPUT 
const name = await bs.target( await bs.getTarget( "EMAIL_INPUT" ) ).getAttr( "name" );       
```

## Jest tools

Please find available API in [official documentation of Jest framework](https://jestjs.io/docs/en/getting-started). Most demanded tool for the context is expect. In the scope of the test it is extended with the following methods:

* **expect( result )**
  * `toBeOk( expectedValue, assertionSource)` - assert the received value is truthy
  * `toBeEqual( expectedValue, assertionSource)` -  assert the received value equals expected one
  * `toIncludeSubstring(expectedSubstring, assertionSource)` - assert the received string contains expected one
  * `toPassCondition(operator, valueToCompare, assertionSource)` - assert the received value satisfies a given Puppetry condition
  * `toMatchBoundingBoxSnapshot(snapshot, assertionSource)` - assert the received bounding box matches a given snapshot
  * `toMatchPosition(position, target, counterpart, assertionSource)` - assert the received position object matches a given one

Examples:

```javascript
// Asserting that page HTML satisfies the given constraint
result = await bs.page.content();       
expect( result ).toIncludeSubstring( "demo", "page.assertContent" );

// Asserting that window scroll offset satisfies the given constraint
result = await ( await bs.page.evaluate( () => window.scrollX ) );       
expect( result ).toPassCondition( "lt", 10000, "page.assertScroll" );

// Asserting that EMAIL_INPUT element is visible
result = await bs.target( await EMAIL_INPUT() ).isVisible();       
expect( result ).toBeOk( "EMAIL_INPUT.assertVisible" );

// Asserting that the bounding box of the element satisfies the given constraint
result = await ( await SUBMIT_BTN() ).boundingBox();    
expect( result ).toMatchBoundingBoxSnapshot( {
       "xOperator": "gt",
       "xValue": 0,
       "yOperator": "gt",
       "yValue": 0,
       "wOperator": "gt",
       "wValue": 0,
       "hOperator": "gt",
       "hValue": 0
     }, "SUBMIT_BTN.assertBoundingBox" );

 // Asserting that the bounding box of the element satisfies the given constraint
result = {
        target: await ( await DAY_SELECT() ).boundingBox(),
        counterpart: await ( await MONTH_SELECT() ).boundingBox()
      };       
expect( result ).toMatchPosition( "left", "DAY_SELECT", "MONTH_SELECT", "DAY_SELECT.assertPosition" );
```

## Helpers

Helpers are functions available in specification (suite) scope

* **util**&#x20;
  * **png** - build screenshot option&#x20;
  * **pollForValue** - poll for value (used by `page.assignVarRemotely`)
  * **exp** - template expressions functions
  * **bytesToString** - translates size into human-readable string
  * **generateTmpUploadFile** - creates a file in temporary directory by given name and size
* **fetch** - [Node.js-implementation](https://www.npmjs.com/package/node-fetch) of window\.fetch
* **localStorage** - [Node.js-implementation](https://www.npmjs.com/package/node-localstorage) of localStorage

`png( id, parentId, screenshotTitle, options ): Object` - build screenshot options

Example:

```javascript
await bs.page.screenshot( util.png( "id", "id", "Just for test", {
  "fullPage":true
}));
```

This command saves screenshot in `./screenshots/All--available--methods/Just-for-test.png` given that test title is *All available methods*

## Node.js

In the test scope one can access [Node.js modules](https://nodejs.org/en/).


---

# 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/command-api.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.