chore(doclint): add basic tests for documentation parsers (#934)

This patch adds basic tests to verify javascript and markdown
documentation parsers.

utils/doclint/check_public_api/test/09-js-builder/foo.js

@@ -0,0 +1,17 @@
+class A {
+  constructor(delegate) {
+    this.property1 = 1;
+    this._property2 = 2;
+  }
+
+  get getter() {
+    return null;
+  }
+
+  async method(foo, bar) {
+  }
+}
+
+A.Events = {
+  AnEvent: 'anevent'
+};

utils/doclint/check_public_api/test/09-js-builder/result.txt

@@ -0,0 +1,56 @@
+{
+  "classes": [
+    {
+      "name": "A",
+      "members": [
+        {
+          "name": "property1",
+          "type": "property",
+          "hasReturn": false,
+          "async": false,
+          "args": []
+        },
+        {
+          "name": "_property2",
+          "type": "property",
+          "hasReturn": false,
+          "async": false,
+          "args": []
+        },
+        {
+          "name": "constructor",
+          "type": "method",
+          "hasReturn": false,
+          "async": false,
+          "args": [
+            "delegate"
+          ]
+        },
+        {
+          "name": "getter",
+          "type": "property",
+          "hasReturn": false,
+          "async": false,
+          "args": []
+        },
+        {
+          "name": "method",
+          "type": "method",
+          "hasReturn": true,
+          "async": true,
+          "args": [
+            "foo",
+            "bar"
+          ]
+        },
+        {
+          "name": "anevent",
+          "type": "event",
+          "hasReturn": false,
+          "async": false,
+          "args": []
+        }
+      ]
+    }
+  ]
+}

utils/doclint/check_public_api/test/10-md-builder/doc.md

@@ -0,0 +1,19 @@
+### class: Foo
+
+This is a class.
+
+#### event: 'frame'
+- <[Frame]> 
+
+This event is dispatched.
+
+#### foo.$(selector)
+- `selector` <[string]> A selector to query page for
+- returns: <[Promise]<[ElementHandle]>>
+
+The method runs document.querySelector.
+
+#### foo.url
+- <[string]>
+
+Contains the URL of the request.

utils/doclint/check_public_api/test/10-md-builder/result.txt

@@ -0,0 +1,32 @@
+{
+  "classes": [
+    {
+      "name": "Foo",
+      "members": [
+        {
+          "name": "frame",
+          "type": "event",
+          "hasReturn": false,
+          "async": false,
+          "args": []
+        },
+        {
+          "name": "$",
+          "type": "method",
+          "hasReturn": true,
+          "async": false,
+          "args": [
+            "selector"
+          ]
+        },
+        {
+          "name": "url",
+          "type": "property",
+          "hasReturn": false,
+          "async": false,
+          "args": []
+        }
+      ]
+    }
+  ]
+}

utils/doclint/check_public_api/test/test.js

@@ -20,6 +20,8 @@ const path = require('path');
 const puppeteer = require('../../../..');
 const checkPublicAPI = require('..');
 const SourceFactory = require('../../SourceFactory');
+const mdBuilder = require('../MDBuilder');
+const jsBuilder = require('../JSBuilder');
 const GoldenUtils = require('../../../../test/golden-utils');
 
 const OUTPUT_DIR = path.join(__dirname, 'output');
@@ -45,17 +47,19 @@ afterAll(SX(async function() {
 }));
 
 describe('checkPublicAPI', function() {
-  it('01-class-errors', SX(test));
+  it('01-class-errors', SX(testLint));
-  it('02-method-errors', SX(test));
+  it('02-method-errors', SX(testLint));
-  it('03-property-errors', SX(test));
+  it('03-property-errors', SX(testLint));
-  it('04-bad-arguments', SX(test));
+  it('04-bad-arguments', SX(testLint));
-  it('05-event-errors', SX(test));
+  it('05-event-errors', SX(testLint));
-  it('06-duplicates', SX(test));
+  it('06-duplicates', SX(testLint));
-  it('07-sorting', SX(test));
+  it('07-sorting', SX(testLint));
-  it('08-return', SX(test));
+  it('08-return', SX(testLint));
+  it('09-js-builder', SX(testJSBuilder));
+  it('10-md-builder', SX(testMDBuilder));
 });
 
-async function test() {
+async function testLint() {
   const dirPath = path.join(__dirname, specName);
   GoldenUtils.addMatchers(jasmine, dirPath, dirPath);
   const factory = new SourceFactory();
@@ -66,6 +70,45 @@ async function test() {
   expect(errors.join('\n')).toBeGolden('result.txt');
 }
 
+async function testMDBuilder() {
+  const dirPath = path.join(__dirname, specName);
+  GoldenUtils.addMatchers(jasmine, dirPath, dirPath);
+  const factory = new SourceFactory();
+  const sources = await factory.readdir(dirPath, '.md');
+  const {documentation} = await mdBuilder(page, sources);
+  expect(serialize(documentation)).toBeGolden('result.txt');
+}
+
+async function testJSBuilder() {
+  const dirPath = path.join(__dirname, specName);
+  GoldenUtils.addMatchers(jasmine, dirPath, dirPath);
+  const factory = new SourceFactory();
+  const sources = await factory.readdir(dirPath, '.js');
+  const {documentation} = await jsBuilder(sources);
+  expect(serialize(documentation)).toBeGolden('result.txt');
+}
+
+function serialize(doc) {
+  const result = {classes: []};
+  for (let cls of doc.classesArray) {
+    const classJSON = {
+      name: cls.name,
+      members: []
+    };
+    result.classes.push(classJSON);
+    for (let member of cls.membersArray) {
+      classJSON.members.push({
+        name: member.name,
+        type: member.type,
+        hasReturn: member.hasReturn,
+        async: member.async,
+        args: member.argsArray.map(arg => arg.name)
+      });
+    }
+  }
+  return JSON.stringify(result, null, 2);
+}
+
 // Since Jasmine doesn't like async functions, they should be wrapped
 // in a SX function.
 function SX(fun) {