# Command API

## 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`)
  * **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"
  });
  
  // Emulating device "Blackberry PlayBook landscape"
  await bs.page.emulate( devices[ "Blackberry PlayBook landscape" ] );
  
  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 SUBMIT_BTN() ).click();   
// Emulating user input
await ( await EMAIL_INPUT() ).type( "json@snow.got" );
// Obtaining "name" attribute's value of EMAIL_INPUT 
const name = await bs.target( await 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
* **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( title, options ): Object` - build screenshot options

Example:

```javascript
await bs.page.screenshot( util.png( "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/).