# 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/).