@open-wc/semantic-dom-diff - npm Package Compare versions

Comparing version 0.8.1 to 0.9.0

CHANGELOG.md

@@ -6,2 +6,13 @@ # Change Log
 
+# [0.9.0](https://github.com/open-wc/open-wc/compare/@open-wc/semantic-dom-diff@0.8.1...@open-wc/semantic-dom-diff@0.9.0) (2019-03-27)
+
+
+### Features
+
+* **semantic-dom-diff:** added option to ignore html in diff ([1d24cc6](https://github.com/open-wc/open-wc/commit/1d24cc6))
+
+
+
+
+
 ## [0.8.1](https://github.com/open-wc/open-wc/compare/@open-wc/semantic-dom-diff@0.8.0...@open-wc/semantic-dom-diff@0.8.1) (2019-03-24)
@@ -8,0 +19,0 @@

index.js

@@ -1,1 +0,43 @@
-export { getDiffableSemanticHTML, getAST } from './src/get-dom-diff.js';
+import getDiff from './dist/get-diffable-html';
+
+/**
+ * @typedef IgnoreAttributesForTags
+ * @property {string[]} tags tags on which to ignore the given attributes
+ * @property {string[]} attributes attributes to ignore for the given tags
+ */
+
+/**
+ * @typedef DiffOptions
+ * @property {(string | IgnoreAttributesForTags)[]} [ignoreAttributes]
+ *  array of attributes to ignore, when given a string that attribute will be ignored on all tags
+ *  when given an object of type `IgnoreAttributesForTags`, you can specify on which tags to ignore which attributes
+ * @property {string[]} [ignoreTags] array of tags to ignore, these tags are stripped from the output
+ * @property {string[]} [ignoreLightDom] array of tags whose light dom to ignore, the light dom of
+ *   these tags are stripped from the output
+ */
+
+/**
+ * Restructures given HTML string, returning it in a format which can be used for comparison:
+ * - whitespace and newlines are normalized
+ * - tags and attributes are printed on individual lines
+ * - comments, style and script tags are removed
+ * - additional tags and attributes can optionally be ignored
+ *
+ * See README.md for details.
+ *
+ * @example
+ * import { getDiffableSemanticHTML } from '@open-wc/semantic-dom-diff';
+ *
+ * const htmlA = getDiffableSemanticHTML(`... some html ...`, { ignoredAttributes: [], ignoredTags: [], ignoreLightDom: [] });
+ * const htmlB = getDiffableSemanticHTML(`... some html ...`);
+ *
+ * // use regular string comparison to spot the differences
+ * expect(htmlA).to.equal(htmlB);
+ *
+ * @param {string} html
+ * @param {DiffOptions} [options]
+ * @returns {string} html restructured in a diffable format
+ */
+export function getDiffableSemanticHTML(html, options) {
+  return getDiff(html, options);
+}

package.json

 {
   "name": "@open-wc/semantic-dom-diff",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "To compare dom and shadow dom trees. Part of open-wc recommendations",
@@ -18,3 +18,3 @@ "author": "open-wc",
   "files": [
-    "src",
+    "dist",
     "index.js"
@@ -28,9 +28,5 @@ ],
     "test:es5:watch": "karma start karma.es5.config.js --auto-watch=true --single-run=false",
-    "prepublishOnly": "../../scripts/insert-header.js"
+    "postinstall": "rollup -c rollup.config.js",
+    "prepublishOnly": "../../scripts/insert-header.js && rollup -c rollup.config.js"
   },
-  "dependencies": {
-    "@bundled-es-modules/diffable-html": "^4.0.0-rc.2",
-    "@bundled-es-modules/parse5": "^5.1.0",
-    "@types/parse5": "^5.0.0"
-  },
   "devDependencies": {
@@ -41,6 +37,14 @@ "@bundled-es-modules/chai": "^4.2.0",
     "@open-wc/testing-wallaby": "^0.1.12",
+    "htmlparser2": "^3.10.1",
     "mocha": "^5.0.0",
+    "rollup": "^1.7.2",
+    "rollup-plugin-commonjs": "^9.2.1",
+    "rollup-plugin-json": "^4.0.0",
+    "rollup-plugin-node-builtins": "^2.1.2",
+    "rollup-plugin-node-globals": "^1.4.0",
+    "rollup-plugin-node-resolve": "^4.0.1",
+    "rollup-plugin-terser": "^4.0.4",
     "webpack-merge": "^4.1.5"
   },
-  "gitHead": "587ef493c6cf7f3306297fb34daf04ede4acb1bc"
+  "gitHead": "abf2c7cc2455ae7026848385f09d09a8ea880c2a"
 }

README.md

@@ -15,19 +15,117 @@ # Semantic Dom Diff
 ```
+`semantic-dom-diff` exports a function which takes a string of HTML, and returns a string of HTML. It restructures given HTML string, returning it in a format which can be used for comparison:
+- whitespace and newlines are normalized
+- tags and attributes are printed on individual lines
+- comments, style and script tags are removed
+- additional tags and attributes can optionally be ignored
 
-## Basics
-
+## Basic usage
 ```javascript
-import { getSemanticDomDiff } from '@open-wc/semantic-dom-diff';
+import { getDiffableSemanticHTML } from '@open-wc/semantic-dom-diff';
 
-const leftTree = `
+const leftTree = getDiffableSemanticHTML(`
   <div>foo</div>
-`;
-const rightTree = `
+`);
+const rightTree = getDiffableSemanticHTML(`
   <div>bar</div>
-`;
+`);
 
-// Diff will be an object if there is a difference, otherwise undefined
-const diff = getSemanticDomDiff(leftTree, rightTree);
+// use any string comparison tool, for example chai:
+expect(leftTree).to.equal(rightTree);
 ```
 
+## Ignoring tags and attributes
+When working with libraries or custom elements there might be parts of the rendered HTML which is random or otherwise outside of your control. In those cases, you might want to ignore certain attributes or tags entirely. This is possible by passing an options object.
+
+### Ignoring an attribute
+```javascript
+import { getDiffableSemanticHTML } from '@open-wc/semantic-dom-diff';
+
+const leftTree = getDiffableSemanticHTML(`
+  <div data-my-attribute="someRandomlyGeneratedDataInAnAttribute">
+    foo
+  </div>
+`, { ignoreAttributes: ['data-my-attribute'] });
+
+const rightTree = getDiffableSemanticHTML(`
+  <div>
+    foo
+  </div>
+`);
+
+// this test will pass, the attribute is ignored
+expect(leftTree).to.equal(rightTree);
+```
+
+### Ignoring an attribute only for certain tags
+Randomly generated ids are often used, throwing off your diffs. You can ignore attributes on specific tags:
+```javascript
+import { getDiffableSemanticHTML } from '@open-wc/semantic-dom-diff';
+
+const leftTree = getDiffableSemanticHTML(`
+  <div>
+    <input id="someRandomlyGeneratedId">
+  </div>
+`, { ignoreAttributes: [{ tags: ['input'], attributs: ['id'] }] });
+
+const rightTree = getDiffableSemanticHTML(`
+  <div>
+    <input>
+  </div>
+`);
+
+// this test will pass, the id attribute is ignored
+expect(leftTree).to.equal(rightTree);
+```
+
+### Ignoring a tag
+Similarly you can tell the diff to ignore certain tags entirely:
+```javascript
+import { getDiffableSemanticHTML } from '@open-wc/semantic-dom-diff';
+
+const leftTree = getDiffableSemanticHTML(`
+  <div>
+    <my-custom-element><my-custom-element>
+    foo
+  </div>
+`, { ignoreTags: ['my-custom-element'] });
+
+const rightTree = getDiffableSemanticHTML(`
+  <div>
+    foo
+  </div>
+`);
+
+// this test will pass, the tag is ignored completely
+expect(leftTree).to.equal(rightTree);
+```
+
+### Ignoring light dom
+When working with web components you may find that they sometimes render to their light dom, for example to meet some accessibility requirements. We don't want to ignore the tag completely, as we would then not be able to test if we did render the tag. We can ignore just it's light dom:
+
+```javascript
+import { getDiffableSemanticHTML } from '@open-wc/semantic-dom-diff';
+
+const leftTree = getDiffableSemanticHTML(`
+  <div>
+    <my-custom-input id="myInput">
+      <input id="inputRenderedInLightDom">
+      Some text rendered in the light dom
+    </my-custom-input>
+    foo
+  </div>
+`, { ignoreLightDom: ['my-custom-element'] });
+
+const rightTree = getDiffableSemanticHTML(`
+  <div>
+    <my-custom-input id="myInput"></my-custom-input>
+    foo
+  </div>
+`);
+
+// this test will pass, the light dom of my-custom-input is ignored, but we can still test
+// to see if the tag is placed properly
+expect(leftTree).to.equal(rightTree);
+```
+
 <script>
@@ -34,0 +132,0 @@ export default {

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Install scripts

Supply chain risk

Install scripts are run when the package is installed. The majority of malware in npm is hidden in install scripts.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

139401

increased by737.24%

Dependency count

0

decreased by-100%

Lines of code

508

increased by418.37%

Number of lines in readme file

141

increased by227.91%

Worsened metrics

Dev dependency count

14

increased by133.33%

Number of package files

6

decreased by-33.33%

Number of high supply chain risk alerts

1

increased byInfinity%

Number of medium supply chain risk alerts

1

increased byInfinity%

Dependency changes

• - Removed@bundled-es-modules/diffable-html@^4.0.0-rc.2

• - Removed@bundled-es-modules/parse5@^5.1.0

• - Removed@types/parse5@^5.0.0

• - Removed@bundled-es-modules/diffable-html@4.0.0(transitive)

• - Removed@bundled-es-modules/parse5@5.1.1(transitive)

• - Removed@types/parse5@5.0.3(transitive)