feat(puppeteer): add takeScreenshot function (#401)

@cybernaut/puppeteer/README.md

@@ -92,6 +92,37 @@ test(
 );
 ```
 
+### Taking an environment-dependent screenshot
+
+`@cybernaut/puppeteer` provides an environment-dependent screenshot function.
+On the CI the screenshot is output as Base64-encoded PNG, locally as PNG file.
+
+**Tip 💡** The Base64-encoded PNG can be visualized by any Online Base64 Image Decoder.
+
+```js
+const {takeScreenshot} = require('@cybernaut/puppeteer/lib/takeScreenshot');
+
+test(
+  'Taking an environment-dependent screenshot',
+  run(({page}) => [
+    async () => page.goto('https://example.com'),
+    async () => console.info('Screenshot:', await takeScreenshot(page))
+  ])
+);
+```
+
+#### Output (`process.env.CI === 'true'`)
+
+```sh
+Screenshot: iVBORw0KGgoAAAANSUhEUgAAAyAAAAJYCAYAAACadoJwAAA...
+```
+
+#### Output (`process.env.CI !== 'true'`)
+
+```sh
+Screenshot: /private/var/folders/dd/5ynm3wcj1y3dsdkzx13d_8qm0000gn/T/92254da8-6df6-4ae2-aae2-29b68fe0f3a4/screenshot.png
+```
+
 ## Type definitions
 
 Because of the lack of publicly available [TypeScript][external-typescript] type definitions for [Puppeteer][external-puppeteer], this package provides its own.
@@ -116,6 +147,14 @@ export declare function createTestSetup(
 export declare function createTestTeardown(): TestTeardown<TestContext>;
 ```
 
+### @cybernaut/puppeteer/lib/takeScreenshot
+
+```ts
+import {Page} from 'puppeteer';
+
+export declare function takeScreenshot(page: Page): Promise<string>;
+```
+
 ---
 Built by (c) Clemens Akens. Released under the terms of the [MIT License][cybernaut-license].
 

@cybernaut/puppeteer/package.json

@@ -18,6 +18,12 @@
   ],
   "dependencies": {
     "@cybernaut/test": "^15.0.0",
-    "puppeteer": "^0.10.2"
+    "puppeteer": "^0.10.2",
+    "temp-write": "^3.3.0"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^4.0.2",
+    "fs-extra": "^4.0.2",
+    "is-png": "^1.1.0"
   }
 }

@cybernaut/puppeteer/src/takeScreenshot.ts

@@ -0,0 +1,17 @@
+/// <reference path="../types/puppeteer.d.ts" />
+
+import tempWrite = require('temp-write');
+
+import {Page} from 'puppeteer';
+
+function isOnCI(): boolean {
+  return process.env.CI === 'true';
+}
+
+export async function takeScreenshot(page: Page): Promise<string> {
+  const screenshot = await page.screenshot({type: 'png'});
+
+  return isOnCI()
+    ? screenshot.toString('base64')
+    : tempWrite(screenshot, 'screenshot.png');
+}

@cybernaut/puppeteer/src/tests/takeScreenshot.test.ts

@@ -0,0 +1,60 @@
+/* tslint:disable no-any */
+
+import isPNG = require('is-png');
+
+import {createTestRunner} from '@cybernaut/test/lib/TestRunner';
+import {readFile} from 'fs-extra';
+import {createTestSetup, createTestTeardown} from '../TestContext';
+import {takeScreenshot} from '../takeScreenshot';
+
+jasmine.DEFAULT_TIMEOUT_INTERVAL = 30 * 1000; /* 30 seconds */
+
+const run = createTestRunner(createTestSetup(), createTestTeardown());
+
+describe('takeScreenshot()', () => {
+  it(
+    'should return a Base64-encoded PNG',
+    run(({page}) => [
+      async () => {
+        const CI = process.env.CI;
+
+        process.env.CI = 'true';
+
+        try {
+          const png = await takeScreenshot(page);
+          const data = new Buffer(png, 'base64');
+
+          expect(isPNG(data)).toBe(true);
+        } finally {
+          process.env.CI = CI;
+        }
+      }
+    ])
+  );
+
+  it(
+    'should write a PNG file and return its filename',
+    run(({page}) => [
+      async () => {
+        const CI = process.env.CI;
+
+        process.env.CI = undefined;
+
+        try {
+          const filename = await takeScreenshot(page);
+
+          expect(filename).toMatch(
+            /* https://stackoverflow.com/a/13653180 */
+            /[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\/screenshot.png$/i
+          );
+
+          const data = await readFile(filename);
+
+          expect(isPNG(data)).toBe(true);
+        } finally {
+          process.env.CI = CI;
+        }
+      }
+    ])
+  );
+});

@cybernaut/puppeteer/types/is-png.d.ts

@@ -0,0 +1,5 @@
+declare module 'is-png' {
+  function isPNG(data: Buffer): boolean;
+
+  export = isPNG;
+}

@cybernaut/puppeteer/types/temp-write.d.ts

@@ -0,0 +1,5 @@
+declare module 'temp-write' {
+  function tempWrite(data: Buffer, name?: string): Promise<string>;
+
+  export = tempWrite;
+}

package.json

@@ -74,7 +74,7 @@
     "transform": {
       ".ts": "<rootDir>/node_modules/ts-jest/preprocessor.js"
     },
-    "verbose": false
+    "verbose": true
   },
   "lint-staged": {
     "*.{ts,tsx}": [