chore: Use expect for assertions (#5581)

Rather than use our own custom expect library, we can use expect from npm [1], which has an API almost identical to the one Puppeteer has, but with more options, better diffing, and is used by many in the community as it's the default assertions library that comes with Jest.

It's also thoroughly documented [2].

[1]: https://www.npmjs.com/package/expect
[2]: https://jestjs.io/docs/en/expect

index.js

@@ -16,12 +16,16 @@
 
 const {helper} = require('./lib/helper');
 const api = require('./lib/api');
+const {Page} = require('./lib/Page');
 for (const className in api) {
   // Puppeteer-web excludes certain classes from bundle, e.g. BrowserFetcher.
   if (typeof api[className] === 'function')
     helper.installAsyncStackHooks(api[className]);
 }
 
+// Expose alias for deprecated method.
+Page.prototype.emulateMedia = Page.prototype.emulateMediaType;
+
 // If node does not support async await, use the compiled version.
 const Puppeteer = require('./lib/Puppeteer');
 const packageJson = require('./package.json');

package.json

@@ -58,6 +58,7 @@
     "cross-env": "^5.0.5",
     "eslint": "^6.8.0",
     "esprima": "^4.0.0",
+    "expect": "^25.2.7",
     "jpeg-js": "^0.3.4",
     "minimist": "^1.2.0",
     "ncp": "^2.0.0",

src/Page.js

@@ -1146,9 +1146,6 @@ class Page extends EventEmitter {
   }
 }
 
-// Expose alias for deprecated method.
-Page.prototype.emulateMedia = Page.prototype.emulateMediaType;
-
 /**
  * @typedef {Object} PDFOptions
  * @property {number=} scale

test/puppeteer.spec.js

@@ -16,8 +16,9 @@
 const fs = require('fs');
 const path = require('path');
 const rm = require('rimraf').sync;
-const GoldenUtils = require('./golden-utils');
-const {Matchers} = require('../utils/testrunner/');
+const utils = require('./utils');
+
+const expect = require('expect');
 
 const YELLOW_COLOR = '\x1b[33m';
 const RESET_COLOR = '\x1b[0m';
@@ -59,13 +60,13 @@ module.exports.addTests = ({testRunner, product, puppeteerPath}) => {
   }
 
   const suffix = FFOX ? 'firefox' : product.toLowerCase();
+
   const GOLDEN_DIR = path.join(__dirname, 'golden-' + suffix);
   const OUTPUT_DIR = path.join(__dirname, 'output-' + suffix);
   if (fs.existsSync(OUTPUT_DIR))
     rm(OUTPUT_DIR);
-  const {expect} = new Matchers({
-    toBeGolden: GoldenUtils.compare.bind(null, GOLDEN_DIR, OUTPUT_DIR)
-  });
+
+  utils.extendExpectWithToBeGolden(GOLDEN_DIR, OUTPUT_DIR);
 
   const testOptions = {
     testRunner,

test/target.spec.js

@@ -27,8 +27,8 @@ module.exports.addTests = function({testRunner, expect, puppeteer}) {
       // The pages will be the testing page and the original newtab page
       const targets = browser.targets();
       expect(targets.some(target => target.type() === 'page' &&
-        target.url() === 'about:blank')).toBeTruthy('Missing blank page');
-      expect(targets.some(target => target.type() === 'browser')).toBeTruthy('Missing browser target');
+        target.url() === 'about:blank')).toBeTruthy();
+      expect(targets.some(target => target.type() === 'browser')).toBeTruthy();
     });
     it('Browser.pages should return all of the pages', async({page, server, context}) => {
       // The pages will be the testing page

test/utils.js

@@ -16,6 +16,8 @@
 
 const fs = require('fs');
 const path = require('path');
+const expect = require('expect');
+const GoldenUtils = require('./golden-utils');
 const {FlakinessDashboard} = require('../utils/flakiness-dashboard');
 const PROJECT_ROOT = fs.existsSync(path.join(__dirname, '..', 'package.json')) ? path.join(__dirname, '..') : path.join(__dirname, '..', '..');
 
@@ -72,6 +74,19 @@ const utils = module.exports = {
     });
   },
 
+  extendExpectWithToBeGolden: function(goldenDir, outputDir) {
+    expect.extend({
+      toBeGolden: (testScreenshot, goldenFilePath) => {
+        const result = GoldenUtils.compare(goldenDir, outputDir, testScreenshot, goldenFilePath);
+
+        return {
+          message: () => result.message,
+          pass: result.pass
+        };
+      }
+    });
+  },
+
   /**
    * @return {string}
    */

utils/browser/test.js

@@ -2,7 +2,8 @@ const path = require('path');
 const fs = require('fs');
 const puppeteer = require('../..');
 const {TestServer} = require('../testserver/');
-const {TestRunner, Reporter, Matchers} = require('../testrunner/');
+const {TestRunner, Reporter} = require('../testrunner/');
+const expect = require('expect');
 
 const puppeteerWebPath = path.join(__dirname, 'puppeteer-web.js');
 if (!fs.existsSync(puppeteerWebPath))
@@ -13,7 +14,6 @@ const testRunner = new TestRunner();
 const {describe, fdescribe, xdescribe} = testRunner;
 const {it, xit, fit} = testRunner;
 const {afterAll, beforeAll, afterEach, beforeEach} = testRunner;
-const {expect} = new Matchers();
 
 beforeAll(async state => {
   const assetsPath = path.join(__dirname, '..', '..', 'test', 'assets');

utils/doclint/check_public_api/test/test.js

@@ -22,7 +22,10 @@ const mdBuilder = require('../MDBuilder');
 const jsBuilder = require('../JSBuilder');
 const GoldenUtils = require('../../../../test/golden-utils');
 
-const {TestRunner, Reporter, Matchers}  = require('../../../testrunner/');
+const testUtils = require('../../../../test/utils')
+
+const {TestRunner, Reporter}  = require('../../../testrunner/');
+const expect = require('expect')
 const runner = new TestRunner();
 const reporter = new Reporter(runner);
 
@@ -60,9 +63,7 @@ runner.run();
 
 async function testLint(state, test) {
   const dirPath = path.join(__dirname, test.name);
-  const {expect} = new Matchers({
-    toBeGolden: GoldenUtils.compare.bind(null, dirPath, dirPath)
-  });
+  testUtils.extendExpectWithToBeGolden(dirPath, dirPath)
 
   const mdSources = await Source.readdir(dirPath, '.md');
   const jsSources = await Source.readdir(dirPath, '.js');
@@ -73,19 +74,18 @@ async function testLint(state, test) {
 
 async function testMDBuilder(state, test) {
   const dirPath = path.join(__dirname, test.name);
-  const {expect} = new Matchers({
-    toBeGolden: GoldenUtils.compare.bind(null, dirPath, dirPath)
-  });
+  testUtils.extendExpectWithToBeGolden(dirPath, dirPath)
+
   const sources = await Source.readdir(dirPath, '.md');
   const {documentation} = await mdBuilder(page, sources);
   expect(serialize(documentation)).toBeGolden('result.txt');
 }
 
 async function testJSBuilder(state, test) {
   const dirPath = path.join(__dirname, test.name);
-  const {expect} = new Matchers({
-    toBeGolden: GoldenUtils.compare.bind(null, dirPath, dirPath)
-  });
+  testUtils.extendExpectWithToBeGolden(dirPath, dirPath)
+
+
   const sources = await Source.readdir(dirPath, '.js');
   const {documentation} = await jsBuilder(sources);
   expect(serialize(documentation)).toBeGolden('result.txt');
@@ -124,4 +124,4 @@ function serializeType(type) {
     name: type.name,
     properties: type.properties.length ? type.properties.map(serializeMember) : undefined
   }
-}
+}

utils/doclint/preprocessor/test.js

@@ -16,14 +16,14 @@
 
 const {runCommands, ensureReleasedAPILinks} = require('.');
 const Source = require('../Source');
-const {TestRunner, Reporter, Matchers}  = require('../../testrunner/');
+const expect = require('expect');
+const {TestRunner, Reporter}  = require('../../testrunner/');
 const runner = new TestRunner();
 new Reporter(runner);
 
 const {describe, xdescribe, fdescribe} = runner;
 const {it, fit, xit} = runner;
 const {beforeAll, beforeEach, afterAll, afterEach} = runner;
-const {expect} = new Matchers();
 
 describe('ensureReleasedAPILinks', function() {
   it('should work with non-release version', function() {

utils/testrunner/README.md

@@ -7,6 +7,7 @@ This test runner is used internally by Puppeteer to test Puppeteer itself.
 - supports async/await
 - modular
 - well-isolated state per execution thread
+- uses the `expect` library from `npm` for assertions.
 
 ### Installation
 
@@ -23,15 +24,14 @@ node test.js
 ```
 
 ```js
-const {TestRunner, Reporter, Matchers} = require('@pptr/testrunner');
+const {TestRunner, Reporter} = require('@pptr/testrunner');
+const expect = require('expect')
 
 // Runner holds and runs all the tests
 const runner = new TestRunner({
   parallel: 2, // run 2 parallel threads
   timeout: 1000, // setup timeout of 1 second per test
 });
-// Simple expect-like matchers
-const {expect} = new Matchers();
 
 // Extract jasmine-like DSL into the global namespace
 const {describe, xdescribe, fdescribe} = runner;

utils/testrunner/examples/fail.js

@@ -14,11 +14,11 @@
  * limitations under the License.
  */
 
-const {TestRunner, Reporter, Matchers} = require('..');
+const {TestRunner, Reporter} = require('..');
 
 const runner = new TestRunner();
 const reporter = new Reporter(runner);
-const {expect} = new Matchers();
+const expect = require('expect');
 
 const {describe, xdescribe, fdescribe} = runner;
 const {it, fit, xit} = runner;

utils/testrunner/examples/hookfail.js

@@ -14,11 +14,11 @@
  * limitations under the License.
  */
 
-const {TestRunner, Reporter, Matchers} = require('..');
+const {TestRunner, Reporter} = require('..');
 
 const runner = new TestRunner();
 const reporter = new Reporter(runner);
-const {expect} = new Matchers();
+const expect = require('expect');
 
 const {describe, xdescribe, fdescribe} = runner;
 const {it, fit, xit} = runner;

utils/testrunner/examples/hooktimeout.js

@@ -14,11 +14,11 @@
  * limitations under the License.
  */
 
-const {TestRunner, Reporter, Matchers} = require('..');
+const {TestRunner, Reporter} = require('..');
 
 const runner = new TestRunner({ timeout: 100 });
 const reporter = new Reporter(runner);
-const {expect} = new Matchers();
+const expect = require('expect');
 
 const {describe, xdescribe, fdescribe} = runner;
 const {it, fit, xit} = runner;