From 462a29f6bbae0d179b71e14f28eb7ff688bfb74e Mon Sep 17 00:00:00 2001
From: Thomas Allmer <d4kmor@gmail.com>
Date: Tue, 6 Aug 2019 01:06:36 +0200
Subject: [PATCH] feat: add type definition files for testing

---
 .circleci/config.yml                          |  7 +++--
 package.json                                  |  3 ++-
 .../chai-a11y-axe/chai-a11y-axe-plugin.d.ts   | 12 +++++++++
 packages/chai-a11y-axe/index.d.ts             |  1 +
 packages/chai-a11y-axe/src/accessible.d.ts    |  7 +++++
 .../chai-dom-diff-plugin.d.ts                 | 17 ++++++++++++
 packages/semantic-dom-diff/chai-dom-diff.d.ts |  7 +++++
 packages/semantic-dom-diff/index.d.ts         |  3 +++
 .../semantic-dom-diff/test/bdd-setup.d.ts     | 13 +++++++++
 .../test/chai-dom-equals.test.js              |  4 +++
 packages/testing-helpers/test/setup.d.ts      | 11 ++++++++
 packages/testing/index-no-side-effects.d.ts   | 26 ++++++++++++++++++
 packages/testing/index.d.ts                   | 27 +++++++++++++++++++
 packages/testing/register-chai-plugins.d.ts   |  1 +
 .../testing/test/semantic-dom-diff.test.js    |  7 ++++-
 tsconfig.build.types.json                     | 23 ++++++++++++++++
 yarn.lock                                     |  5 ++++
 17 files changed, 170 insertions(+), 4 deletions(-)
 create mode 100644 packages/chai-a11y-axe/chai-a11y-axe-plugin.d.ts
 create mode 100644 packages/chai-a11y-axe/index.d.ts
 create mode 100644 packages/chai-a11y-axe/src/accessible.d.ts
 create mode 100644 packages/semantic-dom-diff/chai-dom-diff-plugin.d.ts
 create mode 100644 packages/semantic-dom-diff/chai-dom-diff.d.ts
 create mode 100644 packages/semantic-dom-diff/index.d.ts
 create mode 100644 packages/semantic-dom-diff/test/bdd-setup.d.ts
 create mode 100644 packages/testing-helpers/test/setup.d.ts
 create mode 100644 packages/testing/index-no-side-effects.d.ts
 create mode 100644 packages/testing/index.d.ts
 create mode 100644 packages/testing/register-chai-plugins.d.ts
 create mode 100644 tsconfig.build.types.json

diff --git a/.circleci/config.yml b/.circleci/config.yml
index ac81cd4e..1a0ae16a 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -14,7 +14,7 @@ jobs:
     <<: *defaults
     steps:
       - checkout
-       # Download and cache dependencies
+      # Download and cache dependencies
       - restore_cache:
           keys:
             - v3-dependencies-{{ checksum "package.json" }}
@@ -29,6 +29,9 @@ jobs:
       # build what needs to be build so we can use it in the next steps
       - run: npm run build
 
+      # auto build typescript definition files (not part of build as locally JsDoc alone is all we need)
+      - run: npm run build:types
+
       # run lint
       - run: npm run lint
 
@@ -48,7 +51,7 @@ jobs:
           at: ~/repo
       - add_ssh_keys:
           fingerprints:
-            - "3f:ea:54:b7:77:13:b6:cf:29:90:2b:19:bb:eb:b5:f1"
+            - '3f:ea:54:b7:77:13:b6:cf:29:90:2b:19:bb:eb:b5:f1'
       - run:
           name: Authenticate with registry
           command: echo "//registry.npmjs.org/:_authToken=$NPM_TOKEN" >> ~/.npmrc
diff --git a/package.json b/package.json
index 8a5b526d..2d64bd54 100644
--- a/package.json
+++ b/package.json
@@ -4,6 +4,7 @@
   "license": "MIT",
   "scripts": {
     "build": "lerna run build",
+    "build:types": "tsc -p tsconfig.build.types.json",
     "lint": "run-p lint:*",
     "lint:eslint": "eslint --ext .js,.html .",
     "lint:prettier": "prettier \"**/*.js\" --list-different || (echo '↑↑ these files are not prettier formatted ↑↑' && exit 1)",
@@ -56,7 +57,7 @@
     "lint-staged": "^9.2.0",
     "npm-run-all": "4.1.3",
     "prettier": "^1.18.2",
-    "typescript": "^3.3.3333",
+    "typescript-temporary-fork-for-jsdoc": "^3.6.0-insiders.20190802",
     "vuepress": "^1.0.0-alpha.30",
     "webpack-merge": "^4.1.5"
   }
diff --git a/packages/chai-a11y-axe/chai-a11y-axe-plugin.d.ts b/packages/chai-a11y-axe/chai-a11y-axe-plugin.d.ts
new file mode 100644
index 00000000..5ea4273a
--- /dev/null
+++ b/packages/chai-a11y-axe/chai-a11y-axe-plugin.d.ts
@@ -0,0 +1,12 @@
+/// <reference types="chai" />
+
+declare namespace Chai {
+  interface Assertion {
+    accessible(options?: Object): Assertion;
+  }
+
+  interface Assert {
+    isAccessible(fixture: any, options?: Object): Assertion;
+    isNotAccessible(fixture: any, options?: Object): Assertion;
+  }
+}
diff --git a/packages/chai-a11y-axe/index.d.ts b/packages/chai-a11y-axe/index.d.ts
new file mode 100644
index 00000000..1ec1ce0b
--- /dev/null
+++ b/packages/chai-a11y-axe/index.d.ts
@@ -0,0 +1 @@
+export { chaiA11yAxe } from "./src/accessible.js";
diff --git a/packages/chai-a11y-axe/src/accessible.d.ts b/packages/chai-a11y-axe/src/accessible.d.ts
new file mode 100644
index 00000000..20ab8933
--- /dev/null
+++ b/packages/chai-a11y-axe/src/accessible.d.ts
@@ -0,0 +1,7 @@
+/// <reference path="../chai-a11y-axe-plugin.d.ts" />
+
+/**
+ * @param {any} chai
+ * @param {any} utils
+ */
+export const chaiA11yAxe: (chai: any, utils: any) => void;
diff --git a/packages/semantic-dom-diff/chai-dom-diff-plugin.d.ts b/packages/semantic-dom-diff/chai-dom-diff-plugin.d.ts
new file mode 100644
index 00000000..e5c99f0d
--- /dev/null
+++ b/packages/semantic-dom-diff/chai-dom-diff-plugin.d.ts
@@ -0,0 +1,17 @@
+/// <reference types="chai" />
+
+declare namespace Chai {
+  interface Assertion {
+    dom: Assertion;
+    lightDom: Assertion;
+    shadowDom: Assertion;
+    equalSnapshot(options?: Object): Assertion;
+  }
+
+  interface Assert {
+    dom: Assertion;
+    lightDom: Assertion;
+    shadowDom: Assertion;
+    equalSnapshot(fixture: any, options?: Object): Assertion;
+  }
+}
diff --git a/packages/semantic-dom-diff/chai-dom-diff.d.ts b/packages/semantic-dom-diff/chai-dom-diff.d.ts
new file mode 100644
index 00000000..cc34fdd2
--- /dev/null
+++ b/packages/semantic-dom-diff/chai-dom-diff.d.ts
@@ -0,0 +1,7 @@
+/// <reference path="chai-dom-diff-plugin.d.ts" />
+
+/**
+ * @param {any} chai
+ * @param {any} utils
+ */
+export const chaiDomDiff: (chai: any, utils: any) => void;
diff --git a/packages/semantic-dom-diff/index.d.ts b/packages/semantic-dom-diff/index.d.ts
new file mode 100644
index 00000000..7653e867
--- /dev/null
+++ b/packages/semantic-dom-diff/index.d.ts
@@ -0,0 +1,3 @@
+export { chaiDomDiff } from "./chai-dom-diff.js";
+import { getDiffableHTML } from "./get-diffable-html.js";
+export { getDiffableHTML, getDiffableHTML as getDiffableSemanticHTML };
diff --git a/packages/semantic-dom-diff/test/bdd-setup.d.ts b/packages/semantic-dom-diff/test/bdd-setup.d.ts
new file mode 100644
index 00000000..e4b4363a
--- /dev/null
+++ b/packages/semantic-dom-diff/test/bdd-setup.d.ts
@@ -0,0 +1,13 @@
+/// <reference path="../chai-dom-diff-plugin.d.ts" />
+
+import chai from 'chai';
+
+type expect = typeof chai.expect;
+type assert = typeof chai.assert;
+type should = typeof chai.should;
+
+declare function expect(...args: Parameters<expect>): ReturnType<expect>;
+declare const assert: assert;
+declare function should(...args: Parameters<should>): ReturnType<should>;
+
+export { expect, assert, should };
diff --git a/packages/semantic-dom-diff/test/chai-dom-equals.test.js b/packages/semantic-dom-diff/test/chai-dom-equals.test.js
index a615cc21..61945429 100644
--- a/packages/semantic-dom-diff/test/chai-dom-equals.test.js
+++ b/packages/semantic-dom-diff/test/chai-dom-equals.test.js
@@ -10,7 +10,9 @@ describe('dom', () => {
 
   it('passes along provided configuration', async () => {
     const el = await fixture('<div foo="bar"></div>');
+    // @ts-ignore
     expect(el).dom.to.equal('<div></div>', { ignoreAttributes: ['foo'] });
+    // @ts-ignore
     assert.dom.equal(el, '<div></div>', { ignoreAttributes: ['foo'] });
   });
 });
@@ -24,7 +26,9 @@ describe('lightDom', () => {
 
   it('passes along provided configuration', async () => {
     const el = await fixture('<div><p foo="bar">foo</p></div>');
+    // @ts-ignore
     expect(el).lightDom.to.equal('<p>foo</p>', { ignoreAttributes: ['foo'] });
+    // @ts-ignore
     assert.lightDom.equal(el, '<p>foo</p>', { ignoreAttributes: ['foo'] });
   });
 });
diff --git a/packages/testing-helpers/test/setup.d.ts b/packages/testing-helpers/test/setup.d.ts
new file mode 100644
index 00000000..532d0101
--- /dev/null
+++ b/packages/testing-helpers/test/setup.d.ts
@@ -0,0 +1,11 @@
+import chai from 'chai';
+
+type expect = typeof chai.expect;
+type assert = typeof chai.assert;
+type should = typeof chai.should;
+
+declare function expect(...args: Parameters<expect>): ReturnType<expect>;
+declare const assert: assert;
+declare function should(...args: Parameters<should>): ReturnType<should>;
+
+export { expect, assert, should };
diff --git a/packages/testing/index-no-side-effects.d.ts b/packages/testing/index-no-side-effects.d.ts
new file mode 100644
index 00000000..1c766b60
--- /dev/null
+++ b/packages/testing/index-no-side-effects.d.ts
@@ -0,0 +1,26 @@
+export { html } from '@open-wc/testing-helpers/index-no-side-effects.js';
+export { unsafeStatic } from '@open-wc/testing-helpers/index-no-side-effects.js';
+export { triggerBlurFor } from '@open-wc/testing-helpers/index-no-side-effects.js';
+export { triggerFocusFor } from '@open-wc/testing-helpers/index-no-side-effects.js';
+export { oneEvent } from '@open-wc/testing-helpers/index-no-side-effects.js';
+export { isIE } from '@open-wc/testing-helpers/index-no-side-effects.js';
+export { defineCE } from '@open-wc/testing-helpers/index-no-side-effects.js';
+export { aTimeout } from '@open-wc/testing-helpers/index-no-side-effects.js';
+export { litFixture } from '@open-wc/testing-helpers/index-no-side-effects.js';
+export { litFixtureSync } from '@open-wc/testing-helpers/index-no-side-effects.js';
+export { fixture } from '@open-wc/testing-helpers/index-no-side-effects.js';
+export { fixtureSync } from '@open-wc/testing-helpers/index-no-side-effects.js';
+export { fixtureCleanup } from '@open-wc/testing-helpers/index-no-side-effects.js';
+export { elementUpdated } from '@open-wc/testing-helpers/index-no-side-effects.js';
+
+import chai from 'chai';
+
+type expect = typeof chai.expect;
+type assert = typeof chai.assert;
+type should = typeof chai.should;
+
+declare function expect(...args: Parameters<expect>): ReturnType<expect>;
+declare const assert: assert;
+declare function should(...args: Parameters<should>): ReturnType<should>;
+
+export { expect, assert, should };
diff --git a/packages/testing/index.d.ts b/packages/testing/index.d.ts
new file mode 100644
index 00000000..9e7995d9
--- /dev/null
+++ b/packages/testing/index.d.ts
@@ -0,0 +1,27 @@
+export { html } from '@open-wc/testing-helpers/index.js';
+export { unsafeStatic } from '@open-wc/testing-helpers/index.js';
+export { triggerBlurFor } from '@open-wc/testing-helpers/index.js';
+export { triggerFocusFor } from '@open-wc/testing-helpers/index.js';
+export { oneEvent } from '@open-wc/testing-helpers/index.js';
+export { isIE } from '@open-wc/testing-helpers/index.js';
+export { defineCE } from '@open-wc/testing-helpers/index.js';
+export { aTimeout } from '@open-wc/testing-helpers/index.js';
+export { nextFrame } from '@open-wc/testing-helpers/index.js';
+export { litFixture } from '@open-wc/testing-helpers/index.js';
+export { litFixtureSync } from '@open-wc/testing-helpers/index.js';
+export { fixture } from '@open-wc/testing-helpers/index.js';
+export { fixtureSync } from '@open-wc/testing-helpers/index.js';
+export { fixtureCleanup } from '@open-wc/testing-helpers/index.js';
+export { elementUpdated } from '@open-wc/testing-helpers/index.js';
+
+import chai from 'chai';
+
+type expect = typeof chai.expect;
+type assert = typeof chai.assert;
+type should = typeof chai.should;
+
+declare function expect(...args: Parameters<expect>): ReturnType<expect>;
+declare const assert: assert;
+declare function should(...args: Parameters<should>): ReturnType<should>;
+
+export { expect, assert, should };
diff --git a/packages/testing/register-chai-plugins.d.ts b/packages/testing/register-chai-plugins.d.ts
new file mode 100644
index 00000000..cb0ff5c3
--- /dev/null
+++ b/packages/testing/register-chai-plugins.d.ts
@@ -0,0 +1 @@
+export {};
diff --git a/packages/testing/test/semantic-dom-diff.test.js b/packages/testing/test/semantic-dom-diff.test.js
index 83c76cb1..b05ff7d7 100644
--- a/packages/testing/test/semantic-dom-diff.test.js
+++ b/packages/testing/test/semantic-dom-diff.test.js
@@ -1,11 +1,16 @@
 import { fixture, expect } from '../index.js';
 
 describe('Plugin: semantic-dom-diff', () => {
-  it('can semantically compare dom trees', async () => {
+  it('can semantically compare full dom trees', async () => {
     const el = await fixture(`<div><!-- comment --><h1>${'Hey'}  </h1>  </div>`);
     expect(el).dom.to.equal('<div><h1>Hey</h1></div>');
   });
 
+  it('can semantically compare lightDom trees', async () => {
+    const el = await fixture(`<div><!-- comment --><h1>${'Hey'}  </h1>  </div>`);
+    expect(el).lightDom.to.equal('<h1>Hey</h1>');
+  });
+
   it('can compare against a snapshot', async () => {
     const el = await fixture(`<div><!-- comment --><h1>${'Hey'}  </h1>  </div>`);
     expect(el).dom.to.equalSnapshot();
diff --git a/tsconfig.build.types.json b/tsconfig.build.types.json
new file mode 100644
index 00000000..fd365ce7
--- /dev/null
+++ b/tsconfig.build.types.json
@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "esnext",
+    "module": "esnext",
+    "moduleResolution": "node",
+    "lib": ["es2017", "dom"],
+    "declaration": true,
+    "allowJs": true,
+    "checkJs": true,
+    "emitDeclarationOnly": true,
+    "strict": false,
+    "noImplicitThis": true,
+    "alwaysStrict": true,
+    "types": ["node", "mocha", "chai"],
+    "esModuleInterop": true
+  },
+  "files": ["browser.d.ts"],
+  "include": [
+    "packages/testing-helpers/*.js",
+    "packages/semantic-dom-diff/get-diffable-html.js",
+    "packages/semantic-dom-diff/src/utils.js"
+  ]
+}
diff --git a/yarn.lock b/yarn.lock
index fbeac8e6..64a1b138 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -15703,6 +15703,11 @@ typeface-oswald@0.0.54:
   resolved "https://registry.yarnpkg.com/typeface-oswald/-/typeface-oswald-0.0.54.tgz#1e253011622cdd50f580c04e7d625e7f449763d7"
   integrity sha512-U1WMNp4qfy4/3khIfHMVAIKnNu941MXUfs3+H9R8PFgnoz42Hh9pboSFztWr86zut0eXC8byalmVhfkiKON/8Q==
 
+typescript-temporary-fork-for-jsdoc@^3.6.0-insiders.20190802:
+  version "3.6.0-insiders.20190802"
+  resolved "https://registry.yarnpkg.com/typescript-temporary-fork-for-jsdoc/-/typescript-temporary-fork-for-jsdoc-3.6.0-insiders.20190802.tgz#aece6f3f5d53c6e06e5e1c4af5a19183d7124ab6"
+  integrity sha512-j76opNh6ljAXDUDXr03+pOkITiATPbUlQlMp9pxD/SR3eNKAtIdHwOTf3dDspyGs8TGJQjQXMUiYqJr0gW+nCg==
+
 typescript@^3.3.3333:
   version "3.5.3"
   resolved "https://registry.yarnpkg.com/typescript/-/typescript-3.5.3.tgz#c830f657f93f1ea846819e929092f5fe5983e977"