From 43593edd3a57a473080fc5dd94a703d0c79c64ce Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Konstantin=20Simon=20Maria=20M=C3=B6llers?=
 <ksm.moellers@gmail.com>
Date: Tue, 12 Jun 2018 18:05:03 +0200
Subject: [PATCH 1/7] [puppeteer] Add @ksm2 to authors

---
 types/puppeteer/index.d.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/types/puppeteer/index.d.ts b/types/puppeteer/index.d.ts
index 9b81adcac7..feefc210ec 100644
--- a/types/puppeteer/index.d.ts
+++ b/types/puppeteer/index.d.ts
@@ -2,6 +2,7 @@
 // Project: https://github.com/GoogleChrome/puppeteer#readme
 // Definitions by: Marvin Hagemeister <https://github.com/marvinhagemeister>
 //                 Christopher Deutsch <https://github.com/cdeutsch>
+//                 Konstantin Simon Maria Möllers <https://github.com/ksm2>
 // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
 // TypeScript Version: 2.3
 

From f1a6aba53c00bf4d20b03f3588ce93a137cf1624 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Konstantin=20Simon=20Maria=20M=C3=B6llers?=
 <ksm.moellers@gmail.com>
Date: Tue, 12 Jun 2018 18:05:47 +0200
Subject: [PATCH 2/7] [puppeteer] Make $eval and $$eval generic

---
 types/puppeteer/index.d.ts | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/types/puppeteer/index.d.ts b/types/puppeteer/index.d.ts
index feefc210ec..37887d3a4f 100644
--- a/types/puppeteer/index.d.ts
+++ b/types/puppeteer/index.d.ts
@@ -776,27 +776,27 @@ export interface FrameBase {
   /**
    * This method runs document.querySelector within the page and passes it as the first argument to `fn`.
    * If there's no element matching selector, the method throws an error.
-   * If `fn` returns a Promise, then $eval would wait for the promise to resolve and return its value.
+   * If `pageFunction` returns a Promise, then $eval would wait for the promise to resolve and return its value.
    */
-  $eval(
+  $eval<T>(
     selector: string,
-    pageFunction: (element: Element, ...args: any[]) => any,
+    pageFunction: (element: Element, ...args: any[]) => T,
     ...args: any[]
-  ): Promise<any>;
+  ): Promise<T>;
 
   /**
    * This method runs document.querySelectorAll within the page and passes it as the first argument to `fn`.
-   * If `fn` returns a Promise, then $$eval would wait for the promise to resolve and return its value.
+   * If `pageFunction` returns a Promise, then $$eval would wait for the promise to resolve and return its value.
    * @param selector A selector to query frame for
    * @param fn Function to be evaluated in browser context
    * @param args Arguments to pass to pageFunction
    * @returns Promise which resolves to the return value of pageFunction
    */
-  $$eval(
+  $$eval<T>(
     selector: string,
-    pageFunction: (elements: NodeListOf<Element>, ...args: any[]) => any,
+    pageFunction: (elements: NodeListOf<Element>, ...args: any[]) => T,
     ...args: any[]
-  ): Promise<any>;
+  ): Promise<T>;
 
   /** Adds a `<script>` tag into the page with the desired url or content. */
   addScriptTag(options: ScriptTagOptions): Promise<void>;

From 8dc71fb832df828c11ec7b655db0dd8d177849e6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Konstantin=20Simon=20Maria=20M=C3=B6llers?=
 <ksm.moellers@gmail.com>
Date: Tue, 12 Jun 2018 18:24:48 +0200
Subject: [PATCH 3/7] [puppeteer] Implement 1.4.0 API

---
 types/puppeteer/index.d.ts | 49 +++++++++++++++++++++++++++++++-------
 1 file changed, 40 insertions(+), 9 deletions(-)

diff --git a/types/puppeteer/index.d.ts b/types/puppeteer/index.d.ts
index 37887d3a4f..bcfb1c500b 100644
--- a/types/puppeteer/index.d.ts
+++ b/types/puppeteer/index.d.ts
@@ -1,4 +1,4 @@
-// Type definitions for puppeteer 1.3
+// Type definitions for puppeteer 1.4
 // Project: https://github.com/GoogleChrome/puppeteer#readme
 // Definitions by: Marvin Hagemeister <https://github.com/marvinhagemeister>
 //                 Christopher Deutsch <https://github.com/cdeutsch>
@@ -454,17 +454,33 @@ export interface Box {
  */
 export interface ElementHandle extends JSHandle {
   /**
-   * The method runs element.querySelector within the page. If no element matches the selector, the return value resolve to null.
+   * The method runs element.querySelector within the page.
+   * If no element matches the selector, the return value resolve to null.
    * @param selector A selector to query element for
    * @since 0.13.0
    */
   $(selector: string): Promise<ElementHandle | null>;
+
   /**
-   * The method runs element.querySelectorAll within the page. If no elements match the selector, the return value resolve to [].
+   * The method runs element.querySelectorAll within the page.
+   * If no elements match the selector, the return value resolve to [].
    * @param selector A selector to query element for
    * @since 0.13.0
    */
   $$(selector: string): Promise<ElementHandle[]>;
+
+  /**
+   * This method runs `document.querySelector` within the element and passes it as the first argument to `pageFunction`.
+   * If there's no element matching `selector`, the method throws an error.
+   *
+   * If `pageFunction` returns a Promise, then `frame.$eval` would wait for the promise to resolve and return its value.
+   */
+  $eval<T>(
+    selector: string,
+    pageFunction: (element: Element, ...args: any[]) => T,
+    ...args: any[]
+  ): Promise<T>;
+
   /**
    * @param selector XPath expression to evaluate.
    */
@@ -760,15 +776,19 @@ export interface Response {
 
 export interface FrameBase {
   /**
-   * The method runs document.querySelector within the page.
-   * If no element matches the selector, the return value resolve to null.
+   * The method queries frame for the selector.
+   * If there's no such element within the frame, the method will resolve to null.
    */
   $(selector: string): Promise<ElementHandle | null>;
+
   /**
-   * The method runs document.querySelectorAll within the page. If no elements match the selector, the return value resolve to [].
+   * The method runs document.querySelectorAll within the frame.
+   * If no elements match the selector, the return value resolve to [].
    */
   $$(selector: string): Promise<ElementHandle[]>;
+
   /**
+   * The method evaluates the XPath expression.
    * @param expression XPath expression to evaluate.
    */
   $x(expression: string): Promise<ElementHandle[]>;
@@ -785,8 +805,8 @@ export interface FrameBase {
   ): Promise<T>;
 
   /**
-   * This method runs document.querySelectorAll within the page and passes it as the first argument to `fn`.
-   * If `pageFunction` returns a Promise, then $$eval would wait for the promise to resolve and return its value.
+   * This method runs document.querySelectorAll within the frame and passes it as the first argument to pageFunction.
+   * If pageFunction returns a Promise, then frame.$$eval would wait for the promise to resolve and return its value.
    * @param selector A selector to query frame for
    * @param fn Function to be evaluated in browser context
    * @param args Arguments to pass to pageFunction
@@ -962,6 +982,11 @@ export interface PageEventObj {
   response: Response;
 }
 
+export interface PageCloseOptions {
+  /** Defaults to `false`. Whether to run the before unload page handlers. */
+  runBeforeUnload?: boolean;
+}
+
 /** Page provides methods to interact with a single tab in Chromium. One Browser instance might have multiple Page instances. */
 export interface Page extends EventEmitter, FrameBase {
   /**
@@ -996,8 +1021,11 @@ export interface Page extends EventEmitter, FrameBase {
   /** Brings page to front (activates tab). */
   bringToFront(): Promise<void>;
 
+  /** Get the browser the page belongs to. */
+  browser(): Promise<Browser>;
+
   /** Closes the current page. */
-  close(): Promise<void>;
+  close(options?: PageCloseOptions): Promise<void>;
 
   /**
    * Gets the cookies.
@@ -1289,6 +1317,9 @@ export interface BrowserEventObj {
 }
 
 export interface Target {
+  /** Get the browser the target belongs to. */
+  browser(): Browser;
+
   /** Creates a Chrome Devtools Protocol session attached to the target. */
   createCDPSession(): Promise<CDPSession>;
 

From 94498aa01cfae725ca435935df5ca65af422ab13 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Konstantin=20Simon=20Maria=20M=C3=B6llers?=
 <ksm.moellers@gmail.com>
Date: Tue, 12 Jun 2018 18:38:16 +0200
Subject: [PATCH 4/7] [puppeteer] Add "background_page" and "browser" to target
 types

---
 types/puppeteer/index.d.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/types/puppeteer/index.d.ts b/types/puppeteer/index.d.ts
index bcfb1c500b..feae93f74f 100644
--- a/types/puppeteer/index.d.ts
+++ b/types/puppeteer/index.d.ts
@@ -1327,7 +1327,7 @@ export interface Target {
   page(): Promise<Page>;
 
   /** Identifies what kind of target this is.  */
-  type(): "page" | "service_worker" | "other";
+  type(): "page" | "background_page" | "service_worker" | "browser" | "other";
 
   /** Returns the target URL. */
   url(): string;

From 39bdabc5b4f6b83d65f16d89930c9b8fba14429d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Konstantin=20Simon=20Maria=20M=C3=B6llers?=
 <ksm.moellers@gmail.com>
Date: Tue, 12 Jun 2018 18:47:49 +0200
Subject: [PATCH 5/7] [puppeteer] Implement 1.5.0 API

---
 types/puppeteer/index.d.ts         | 128 ++++++++++++++++++++++++++++-
 types/puppeteer/puppeteer-tests.ts |  25 ++++++
 2 files changed, 151 insertions(+), 2 deletions(-)

diff --git a/types/puppeteer/index.d.ts b/types/puppeteer/index.d.ts
index feae93f74f..ad12c17e99 100644
--- a/types/puppeteer/index.d.ts
+++ b/types/puppeteer/index.d.ts
@@ -1,4 +1,4 @@
-// Type definitions for puppeteer 1.4
+// Type definitions for puppeteer 1.5
 // Project: https://github.com/GoogleChrome/puppeteer#readme
 // Definitions by: Marvin Hagemeister <https://github.com/marvinhagemeister>
 //                 Christopher Deutsch <https://github.com/cdeutsch>
@@ -148,7 +148,9 @@ export type PageEvents =
   | "request"
   | "requestfailed"
   | "requestfinished"
-  | "response";
+  | "response"
+  | "workercreated"
+  | "workerdestroyed";
 
 export type BrowserEvents =
   | "disconnected"
@@ -449,6 +451,37 @@ export interface Box {
   y: number;
 }
 
+/**
+ * The Worker class represents a WebWorker.
+ * The events workercreated and workerdestroyed are emitted on the page object to signal the worker lifecycle.
+ */
+export interface Worker {
+  /**
+   * If the function passed to the `worker.evaluate` returns a Promise,
+   * then `worker.evaluate` would wait for the promise to resolve and return its value.
+   *
+   * If the function passed to the `worker.evaluate` returns a non-Serializable value,
+   * then `worker.evaluate` resolves to `undefined`.
+   */
+  evaluate<T>(
+    pageFunction: (...args: any[]) => T | Promise<T>,
+    ...args: any[],
+  ): Promise<T>;
+
+  /**
+   * The only difference between `worker.evaluate` and `worker.evaluateHandle` is
+   * that `worker.evaluateHandle` returns in-page object (JSHandle).
+   */
+  evaluateHandle<T>(
+    pageFunction: (...args: any[]) => T | Promise<T>,
+    ...args: any[],
+  ): Promise<T>;
+
+  executionContext(): Promise<ExecutionContext>;
+
+  url(): string;
+}
+
 /**
  * Represents an in-page DOM element. ElementHandles can be created with the page.$ method.
  */
@@ -696,6 +729,10 @@ export interface Request {
    * All header names are lower-case.
    */
   headers(): Headers;
+
+  /** Whether this request is driving frame's navigation. */
+   isNavigationRequest(): boolean;
+
   /** Returns the request's method (GET, POST, etc.) */
 
   method(): HttpMethod;
@@ -980,6 +1017,10 @@ export interface PageEventObj {
   requestfinished: Request;
   /** Emitted when a response is received. */
   response: Response;
+  /** Emitted when a dedicated WebWorker is spawned by the page. */
+  workercreated: Worker;
+  /** Emitted when a dedicated WebWorker is terminated. */
+  workerdestroyed: Worker;
 }
 
 export interface PageCloseOptions {
@@ -1105,6 +1146,9 @@ export interface Page extends EventEmitter, FrameBase {
   /** Returns the virtual keyboard. */
   keyboard: Keyboard;
 
+  /** Indicates that the page has been closed. */
+  isClosed(): boolean;
+
   /** Page is guaranteed to have a main frame which persists during navigation's. */
   mainFrame(): Frame;
 
@@ -1238,6 +1282,9 @@ export interface Page extends EventEmitter, FrameBase {
    * @param options The navigation parameters.
    */
   waitForNavigation(options?: NavigationOptions): Promise<Response>;
+
+  /** This method returns all of the dedicated WebWorkers associated with the page. */
+  workers(): Worker[];
 }
 
 /** A Browser is created when Puppeteer connects to a Chromium instance, either through puppeteer.launch or puppeteer.connect. */
@@ -1265,12 +1312,24 @@ export interface Browser extends EventEmitter {
     handler: (e: BrowserEventObj[K], ...args: any[]) => void
   ): this;
 
+  /**
+   * Returns an array of all open browser contexts.
+   * In a newly created browser, this will return a single instance of BrowserContext.
+   */
+  browserContexts(): BrowserContext[];
+
   /**
    * Closes browser with all the pages (if any were opened).
    * The browser object itself is considered to be disposed and can not be used anymore.
    */
   close(): Promise<void>;
 
+  /**
+   * Creates a new incognito browser context.
+   * This won't share cookies/cache with other browser contexts.
+   */
+  createIncognitoBrowserContext(): Promise<BrowserContext>;
+
   /**
    * Disconnects Puppeteer from the browser, but leaves the Chromium process running.
    * After calling `disconnect`, the browser object is considered disposed and cannot be used anymore.
@@ -1316,13 +1375,78 @@ export interface BrowserEventObj {
   targetdestroyed: Target;
 }
 
+/**
+ * BrowserContexts provide a way to operate multiple independent browser sessions.
+ * When a browser is launched, it has a single BrowserContext used by default.
+ * The method `browser.newPage()` creates a page in the default browser context.
+ */
+export interface BrowserContext extends EventEmitter {
+  /**
+   * Adds the listener function to the end of the listeners array for the event named `eventName`.
+   * No checks are made to see if the listener has already been added. Multiple calls passing the same combination of
+   * `eventName` and listener will result in the listener being added, and called, multiple times.
+   * @param event The name of the event.
+   * @param handler The callback function.
+   */
+  on<K extends keyof BrowserContextEventObj>(
+    eventName: K,
+    handler: (e: BrowserContextEventObj[K], ...args: any[]) => void
+  ): this;
+
+  /**
+   * Adds a one time listener function for the event named `eventName`.
+   * The next time `eventName` is triggered, this listener is removed and then invoked.
+   * @param event The name of the event.
+   * @param handler The callback function.
+   */
+  once<K extends keyof BrowserContextEventObj>(
+    eventName: K,
+    handler: (e: BrowserContextEventObj[K], ...args: any[]) => void
+  ): this;
+
+  /** The browser this browser context belongs to. */
+  browser(): Browser;
+
+  /** Closes the browser context. All the targets that belong to the browser context will be closed. */
+  close(): Promise<void>;
+
+  /**
+   * Returns whether BrowserContext is incognito.
+   * The default browser context is the only non-incognito browser context.
+   */
+  isIncognito(): boolean;
+
+  /** Creates a new page in the browser context. */
+  newPage(): Promise<Page>;
+
+  /** An array of all active targets inside the browser context. */
+  targets(): Target[];
+}
+
+export interface BrowserContextEventObj {
+  /** Emitted when the url of a target inside the browser context changes. */
+  targetchanged: Target;
+
+  /** Emitted when a target is created, for example when a new page is opened by `window.open` or `browserContext.newPage`. */
+  targetcreated: Target;
+
+  /** Emitted when a target is destroyed, for example when a page is closed. */
+  targetdestroyed: Target;
+}
+
 export interface Target {
   /** Get the browser the target belongs to. */
   browser(): Browser;
 
+  /** The browser context the target belongs to. */
+  browserContext(): BrowserContext;
+
   /** Creates a Chrome Devtools Protocol session attached to the target. */
   createCDPSession(): Promise<CDPSession>;
 
+  /** Get the target that opened this target. Top-level targets return `null`. */
+  opener(): Target | null;
+
   /** Returns the target `Page` or a `null` if the type of the page is not "page". */
   page(): Promise<Page>;
 
diff --git a/types/puppeteer/puppeteer-tests.ts b/types/puppeteer/puppeteer-tests.ts
index 05065e043a..27b9471964 100644
--- a/types/puppeteer/puppeteer-tests.ts
+++ b/types/puppeteer/puppeteer-tests.ts
@@ -338,3 +338,28 @@ puppeteer.launch().then(async browser => {
 
   await page.tracing.start({ path: "trace.json", categories: ["one", "two"] });
 });
+
+// 1.5: From the BrowserContext example
+(async () => {
+  const browser = await puppeteer.launch();
+  // Create a new incognito browser context
+  const context = await browser.createIncognitoBrowserContext();
+  // Create a new page inside context.
+  const page = await context.newPage();
+  // ... do stuff with page ...
+  await page.goto('https://example.com');
+  // Dispose context once it's no longer needed.
+  await context.close();
+});
+
+// 1.5: From the Worker example
+(async () => {
+  const browser = await puppeteer.launch();
+  const page = await browser.newPage();
+  page.on('workercreated', worker => console.log('Worker created: ' + worker.url()));
+  page.on('workerdestroyed', worker => console.log('Worker destroyed: ' + worker.url()));
+
+  console.log('Current workers:');
+  for (const worker of page.workers())
+    console.log('  ' + worker.url());
+});

From b34bd2c86389405b24d8e710d81ab45097c73158 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Konstantin=20Simon=20Maria=20M=C3=B6llers?=
 <ksm.moellers@gmail.com>
Date: Mon, 18 Jun 2018 21:36:27 +0200
Subject: [PATCH 6/7] [puppeteer] Improve typings for $eval and $$eval

- Require TypeScript Version 2.8 in puppeteer
- Use conditional types to wrap or unwrap `ElementHandle`
- Define an `Evalable` interface for `Page`, `Frame` and `ElementHandle`
- Require TypeScript Version 2.8 in jest-environment-puppeteer
- Require TypeScript Version 2.8 in expect-puppeteer
- Require TypeScript Version 2.8 in storybook__addon-storyshots
---
 types/expect-puppeteer/index.d.ts            |   2 +-
 types/jest-environment-puppeteer/index.d.ts  |   2 +-
 types/puppeteer/index.d.ts                   | 230 +++++++++++++++----
 types/puppeteer/puppeteer-tests.ts           |  20 +-
 types/storybook__addon-storyshots/index.d.ts |   2 +-
 5 files changed, 209 insertions(+), 47 deletions(-)

diff --git a/types/expect-puppeteer/index.d.ts b/types/expect-puppeteer/index.d.ts
index 4d599f99fe..24675ee695 100644
--- a/types/expect-puppeteer/index.d.ts
+++ b/types/expect-puppeteer/index.d.ts
@@ -2,7 +2,7 @@
 // Project: https://github.com/smooth-code/jest-puppeteer/tree/master/packages/expect-puppeteer
 // Definitions by: Josh Goldberg <https://github.com/JoshuaKGoldberg>
 // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
-// TypeScript Version: 2.4
+// TypeScript Version: 2.8
 
 /// <reference types="jest" />
 
diff --git a/types/jest-environment-puppeteer/index.d.ts b/types/jest-environment-puppeteer/index.d.ts
index e22bee2f7d..79c25e32d8 100644
--- a/types/jest-environment-puppeteer/index.d.ts
+++ b/types/jest-environment-puppeteer/index.d.ts
@@ -2,7 +2,7 @@
 // Project: https://github.com/smooth-code/jest-puppeteer/tree/master/packages/jest-environment-puppeteer
 // Definitions by: Josh Goldberg <https://github.com/joshuakgoldberg>
 // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
-// TypeScript Version: 2.3
+// TypeScript Version: 2.8
 
 import { Browser, Page } from "puppeteer";
 
diff --git a/types/puppeteer/index.d.ts b/types/puppeteer/index.d.ts
index ad12c17e99..32cab93ca5 100644
--- a/types/puppeteer/index.d.ts
+++ b/types/puppeteer/index.d.ts
@@ -4,13 +4,200 @@
 //                 Christopher Deutsch <https://github.com/cdeutsch>
 //                 Konstantin Simon Maria Möllers <https://github.com/ksm2>
 // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
-// TypeScript Version: 2.3
+// TypeScript Version: 2.8
 
 /// <reference types="node" />
 
 import { EventEmitter } from "events";
 import { ChildProcess } from "child_process";
 
+/** Wraps a DOM element into an ElementHandle instance */
+export type WrapElementHandle<X> = X extends Element ? ElementHandle<X> : X;
+
+/** Unwraps a DOM element out of an ElementHandle instance */
+export type UnwrapElementHandle<X> = X extends ElementHandle<infer E> ? E : X;
+
+/** Defines `$eval` and `$$eval` for Page, Frame and ElementHandle. */
+export interface Evalable {
+  /**
+   * This method runs `document.querySelector` within the context and passes it as the first argument to `pageFunction`.
+   * If there's no element matching `selector`, the method throws an error.
+   *
+   * If `pageFunction` returns a Promise, then `$eval` would wait for the promise to resolve and return its value.
+   *
+   * @param selector A selector to query for
+   * @param pageFunction Function to be evaluated in browser context
+   * @returns Promise which resolves to the return value of pageFunction
+   */
+  $eval<R>(
+    selector: string,
+    pageFunction: (element: Element) => R | Promise<R>,
+  ): Promise<WrapElementHandle<R>>;
+
+  /**
+   * This method runs `document.querySelector` within the context and passes it as the first argument to `pageFunction`.
+   * If there's no element matching `selector`, the method throws an error.
+   *
+   * If `pageFunction` returns a Promise, then `$eval` would wait for the promise to resolve and return its value.
+   *
+   * @param selector A selector to query for
+   * @param pageFunction Function to be evaluated in browser context
+   * @param x1 First argument to pass to pageFunction
+   * @returns Promise which resolves to the return value of pageFunction
+   */
+  $eval<R, X1>(
+    selector: string,
+    pageFunction: (element: Element, x1: UnwrapElementHandle<X1>) => R | Promise<R>,
+    x1: X1,
+  ): Promise<WrapElementHandle<R>>;
+
+  /**
+   * This method runs `document.querySelector` within the context and passes it as the first argument to `pageFunction`.
+   * If there's no element matching `selector`, the method throws an error.
+   *
+   * If `pageFunction` returns a Promise, then `$eval` would wait for the promise to resolve and return its value.
+   *
+   * @param selector A selector to query for
+   * @param pageFunction Function to be evaluated in browser context
+   * @param x1 First argument to pass to pageFunction
+   * @param x2 Second argument to pass to pageFunction
+   * @returns Promise which resolves to the return value of pageFunction
+   */
+  $eval<R, X1, X2>(
+    selector: string,
+    pageFunction: (element: Element, x1: UnwrapElementHandle<X1>, x2: UnwrapElementHandle<X2>) => R | Promise<R>,
+    x1: X1,
+    x2: X2,
+  ): Promise<WrapElementHandle<R>>;
+
+  /**
+   * This method runs `document.querySelector` within the context and passes it as the first argument to `pageFunction`.
+   * If there's no element matching `selector`, the method throws an error.
+   *
+   * If `pageFunction` returns a Promise, then `$eval` would wait for the promise to resolve and return its value.
+   *
+   * @param selector A selector to query for
+   * @param pageFunction Function to be evaluated in browser context
+   * @param x1 First argument to pass to pageFunction
+   * @param x2 Second argument to pass to pageFunction
+   * @param x3 Third argument to pass to pageFunction
+   * @returns Promise which resolves to the return value of pageFunction
+   */
+  $eval<R, X1, X2, X3>(
+    selector: string,
+    pageFunction: (element: Element, x1: UnwrapElementHandle<X1>, x2: UnwrapElementHandle<X2>, x3: UnwrapElementHandle<X3>) => R | Promise<R>,
+    x1: X1,
+    x2: X2,
+    x3: X3,
+  ): Promise<WrapElementHandle<R>>;
+
+  /**
+   * This method runs `document.querySelector` within the context and passes it as the first argument to `pageFunction`.
+   * If there's no element matching `selector`, the method throws an error.
+   *
+   * If `pageFunction` returns a Promise, then `$eval` would wait for the promise to resolve and return its value.
+   *
+   * @param selector A selector to query for
+   * @param pageFunction Function to be evaluated in browser context
+   * @param args Arguments to pass to pageFunction
+   * @returns Promise which resolves to the return value of pageFunction
+   */
+  $eval<R>(
+    selector: string,
+    pageFunction: (element: Element, ...args: any[]) => R | Promise<R>,
+    ...args: any[],
+  ): Promise<WrapElementHandle<R>>;
+
+  /**
+   * This method runs `Array.from(document.querySelectorAll(selector))` within the context and passes it as the
+   * first argument to `pageFunction`.
+   *
+   * If `pageFunction` returns a Promise, then `$$eval` would wait for the promise to resolve and return its value.
+   *
+   * @param selector A selector to query for
+   * @param pageFunction Function to be evaluated in browser context
+   * @returns Promise which resolves to the return value of pageFunction
+   */
+  $$eval<R>(
+    selector: string,
+    pageFunction: (elements: Element[]) => R | Promise<R>,
+  ): Promise<WrapElementHandle<R>>;
+
+  /**
+   * This method runs `Array.from(document.querySelectorAll(selector))` within the context and passes it as the
+   * first argument to `pageFunction`.
+   *
+   * If `pageFunction` returns a Promise, then `$$eval` would wait for the promise to resolve and return its value.
+   *
+   * @param selector A selector to query for
+   * @param pageFunction Function to be evaluated in browser context
+   * @param x1 First argument to pass to pageFunction
+   * @returns Promise which resolves to the return value of pageFunction
+   */
+  $$eval<R, X1>(
+    selector: string,
+    pageFunction: (elements: Element[], x1: UnwrapElementHandle<X1>) => R | Promise<R>,
+    x1: X1,
+  ): Promise<WrapElementHandle<R>>;
+
+  /**
+   * This method runs `Array.from(document.querySelectorAll(selector))` within the context and passes it as the
+   * first argument to `pageFunction`.
+   *
+   * If `pageFunction` returns a Promise, then `$$eval` would wait for the promise to resolve and return its value.
+   *
+   * @param selector A selector to query for
+   * @param pageFunction Function to be evaluated in browser context
+   * @param x1 First argument to pass to pageFunction
+   * @param x2 Second argument to pass to pageFunction
+   * @returns Promise which resolves to the return value of pageFunction
+   */
+  $$eval<R, X1, X2>(
+    selector: string,
+    pageFunction: (elements: Element[], x1: UnwrapElementHandle<X1>, x2: UnwrapElementHandle<X2>) => R | Promise<R>,
+    x1: X1,
+    x2: X2,
+  ): Promise<WrapElementHandle<R>>;
+
+  /**
+   * This method runs `Array.from(document.querySelectorAll(selector))` within the context and passes it as the
+   * first argument to `pageFunction`.
+   *
+   * If `pageFunction` returns a Promise, then `$$eval` would wait for the promise to resolve and return its value.
+   *
+   * @param selector A selector to query for
+   * @param pageFunction Function to be evaluated in browser context
+   * @param x1 First argument to pass to pageFunction
+   * @param x2 Second argument to pass to pageFunction
+   * @param x3 Third argument to pass to pageFunction
+   * @returns Promise which resolves to the return value of pageFunction
+   */
+  $$eval<R, X1, X2, X3>(
+    selector: string,
+    pageFunction: (elements: Element[], x1: UnwrapElementHandle<X1>, x2: UnwrapElementHandle<X2>, x3: UnwrapElementHandle<X3>) => R | Promise<R>,
+    x1: X1,
+    x2: X2,
+    x3: X3,
+  ): Promise<WrapElementHandle<R>>;
+
+  /**
+   * This method runs `Array.from(document.querySelectorAll(selector))` within the context and passes it as the
+   * first argument to `pageFunction`.
+   *
+   * If `pageFunction` returns a Promise, then `$$eval` would wait for the promise to resolve and return its value.
+   *
+   * @param selector A selector to query for
+   * @param pageFunction Function to be evaluated in browser context
+   * @param args Arguments to pass to pageFunction
+   * @returns Promise which resolves to the return value of pageFunction
+   */
+  $$eval<R>(
+    selector: string,
+    pageFunction: (elements: Element[], ...args: any[]) => R | Promise<R>,
+    ...args: any[]
+  ): Promise<WrapElementHandle<R>>;
+}
+
 /** Keyboard provides an api for managing a virtual keyboard. */
 export interface Keyboard {
   /**
@@ -485,7 +672,7 @@ export interface Worker {
 /**
  * Represents an in-page DOM element. ElementHandles can be created with the page.$ method.
  */
-export interface ElementHandle extends JSHandle {
+export interface ElementHandle<E extends Element = Element> extends JSHandle, Evalable {
   /**
    * The method runs element.querySelector within the page.
    * If no element matches the selector, the return value resolve to null.
@@ -502,18 +689,6 @@ export interface ElementHandle extends JSHandle {
    */
   $$(selector: string): Promise<ElementHandle[]>;
 
-  /**
-   * This method runs `document.querySelector` within the element and passes it as the first argument to `pageFunction`.
-   * If there's no element matching `selector`, the method throws an error.
-   *
-   * If `pageFunction` returns a Promise, then `frame.$eval` would wait for the promise to resolve and return its value.
-   */
-  $eval<T>(
-    selector: string,
-    pageFunction: (element: Element, ...args: any[]) => T,
-    ...args: any[]
-  ): Promise<T>;
-
   /**
    * @param selector XPath expression to evaluate.
    */
@@ -811,7 +986,7 @@ export interface Response {
   url(): string;
 }
 
-export interface FrameBase {
+export interface FrameBase extends Evalable {
   /**
    * The method queries frame for the selector.
    * If there's no such element within the frame, the method will resolve to null.
@@ -830,31 +1005,6 @@ export interface FrameBase {
    */
   $x(expression: string): Promise<ElementHandle[]>;
 
-  /**
-   * This method runs document.querySelector within the page and passes it as the first argument to `fn`.
-   * If there's no element matching selector, the method throws an error.
-   * If `pageFunction` returns a Promise, then $eval would wait for the promise to resolve and return its value.
-   */
-  $eval<T>(
-    selector: string,
-    pageFunction: (element: Element, ...args: any[]) => T,
-    ...args: any[]
-  ): Promise<T>;
-
-  /**
-   * This method runs document.querySelectorAll within the frame and passes it as the first argument to pageFunction.
-   * If pageFunction returns a Promise, then frame.$$eval would wait for the promise to resolve and return its value.
-   * @param selector A selector to query frame for
-   * @param fn Function to be evaluated in browser context
-   * @param args Arguments to pass to pageFunction
-   * @returns Promise which resolves to the return value of pageFunction
-   */
-  $$eval<T>(
-    selector: string,
-    pageFunction: (elements: NodeListOf<Element>, ...args: any[]) => T,
-    ...args: any[]
-  ): Promise<T>;
-
   /** Adds a `<script>` tag into the page with the desired url or content. */
   addScriptTag(options: ScriptTagOptions): Promise<void>;
 
diff --git a/types/puppeteer/puppeteer-tests.ts b/types/puppeteer/puppeteer-tests.ts
index 27b9471964..baf573ebd2 100644
--- a/types/puppeteer/puppeteer-tests.ts
+++ b/types/puppeteer/puppeteer-tests.ts
@@ -275,16 +275,20 @@ puppeteer.launch().then(async browser => {
   const browser = await puppeteer.launch();
   const page = await browser.newPage();
   await page.goto("https://example.com");
-  let elementText = await page.$eval('#someElement', (element) => {
+  const elementText = await page.$eval('#someElement', (element) => {
     return element.innerHTML;
   });
 
-  elementText = await page.$$eval('.someClassName', (elements) => {
+  // If one returns a DOM reference, puppeteer will wrap an ElementHandle instead
+  const someElement: puppeteer.ElementHandle<HTMLDivElement> = await page.$$eval('.someClassName', (elements) => {
     console.log(elements.length);
-    console.log(elements.item(0).outerHTML);
-    return elements[3].innerHTML;
+    console.log(elements[0].outerHTML);
+    return elements[3] as HTMLDivElement;
   });
 
+  // If one passes an ElementHandle, puppeteer will unwrap its DOM reference instead
+  await page.$eval('.hello-world', (e, x1: HTMLDivElement) => x1.noWrap, someElement);
+
   browser.close();
 })();
 
@@ -363,3 +367,11 @@ puppeteer.launch().then(async browser => {
   for (const worker of page.workers())
     console.log('  ' + worker.url());
 });
+
+// Test conditional types
+(async () => {
+  const browser = await puppeteer.launch();
+  const page = await browser.newPage();
+  const eh: puppeteer.ElementHandle<HTMLTableRowElement> = (await page.$('tr.something'))!;
+  const index: number = await page.$eval('.demo', (e, x1) => x1.rowIndex, eh);
+});
diff --git a/types/storybook__addon-storyshots/index.d.ts b/types/storybook__addon-storyshots/index.d.ts
index e703f374da..dc1a2c5953 100644
--- a/types/storybook__addon-storyshots/index.d.ts
+++ b/types/storybook__addon-storyshots/index.d.ts
@@ -2,7 +2,7 @@
 // Project: https://github.com/storybooks/storybook/tree/master/addons/storyshots
 // Definitions by: Bradley Ayers <https://github.com/bradleyayers>
 // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
-// TypeScript Version: 2.6
+// TypeScript Version: 2.8
 
 import * as React from 'react';
 import { StoryObject } from '@storybook/react';

From faf255a762c64fe582ab5c690f02071aa513c3d2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Konstantin=20Simon=20Maria=20M=C3=B6llers?=
 <ksm.moellers@gmail.com>
Date: Wed, 20 Jun 2018 09:02:38 +0200
Subject: [PATCH 7/7] [puppeteer] Add $ExpectType annotations

---
 types/puppeteer/puppeteer-tests.ts | 41 ++++++++++++++++++++++--------
 1 file changed, 31 insertions(+), 10 deletions(-)

diff --git a/types/puppeteer/puppeteer-tests.ts b/types/puppeteer/puppeteer-tests.ts
index baf573ebd2..96cb4fd361 100644
--- a/types/puppeteer/puppeteer-tests.ts
+++ b/types/puppeteer/puppeteer-tests.ts
@@ -275,16 +275,29 @@ puppeteer.launch().then(async browser => {
   const browser = await puppeteer.launch();
   const page = await browser.newPage();
   await page.goto("https://example.com");
-  const elementText = await page.$eval('#someElement', (element) => {
-    return element.innerHTML;
-  });
+  const elementText = await page.$eval(
+    '#someElement',
+    (
+      element,  // $ExpectType Element
+    ) => {
+      element.innerHTML; // $ExpectType string
+      return element.innerHTML;
+    }
+  );
+  elementText; // $ExpectType string
 
   // If one returns a DOM reference, puppeteer will wrap an ElementHandle instead
-  const someElement: puppeteer.ElementHandle<HTMLDivElement> = await page.$$eval('.someClassName', (elements) => {
-    console.log(elements.length);
-    console.log(elements[0].outerHTML);
-    return elements[3] as HTMLDivElement;
-  });
+  const someElement = await page.$$eval(
+    '.someClassName',
+    (
+      elements, // $ExpectType Element[]
+    ) => {
+      console.log(elements.length);
+      console.log(elements[0].outerHTML);
+      return elements[3] as HTMLDivElement;
+    }
+  );
+  someElement; // $ExpectType ElementHandle<HTMLDivElement>
 
   // If one passes an ElementHandle, puppeteer will unwrap its DOM reference instead
   await page.$eval('.hello-world', (e, x1: HTMLDivElement) => x1.noWrap, someElement);
@@ -372,6 +385,14 @@ puppeteer.launch().then(async browser => {
 (async () => {
   const browser = await puppeteer.launch();
   const page = await browser.newPage();
-  const eh: puppeteer.ElementHandle<HTMLTableRowElement> = (await page.$('tr.something'))!;
-  const index: number = await page.$eval('.demo', (e, x1) => x1.rowIndex, eh);
+  const eh = await page.$('tr.something') as puppeteer.ElementHandle<HTMLTableRowElement>;
+  const index = await page.$eval(
+    '.demo',
+    (
+      e, // $ExpectType Element
+      x1, // $ExpectType HTMLTableRowElement
+    ) => x1.rowIndex,
+    eh,
+  );
+  index; // $ExpectType number
 });