docs: new features

closes #289

docs/articles/api/ngMocks.md

@@ -30,12 +30,17 @@ access desired elements and instances in fixtures.
 * [`find()`](ngMocks/find.md)
 * [`findAll()`](ngMocks/findAll.md)
 
-- [`get()`](ngMocks/get.md)
-- [`findInstance()`](ngMocks/findInstance.md)
-- [`findInstances()`](ngMocks/findInstances.md)
+- [`reveal()`](ngMocks/reveal.md)
+- [`revealAll()`](ngMocks/revealAll.md)
 
-* [`findTemplateRef()`](ngMocks/findTemplateRef.md)
-* [`findTemplateRefs()`](ngMocks/findTemplateRefs.md)
+* [`get()`](ngMocks/get.md)
+* [`findInstance()`](ngMocks/findInstance.md)
+* [`findInstances()`](ngMocks/findInstances.md)
+
+- [`findTemplateRef()`](ngMocks/findTemplateRef.md)
+- [`findTemplateRefs()`](ngMocks/findTemplateRefs.md)
+
+* [`crawl()`](ngMocks/crawl.md)
 
 ## Stubbing methods and properties
 
@@ -47,7 +52,7 @@ access desired elements and instances in fixtures.
 - [`guts()`](ngMocks/guts.md)
 - [`faster()`](ngMocks/faster.md)
 - [`throwOnConsole()`](ngMocks/throwOnConsole.md)
-- `formatHtml()` - removes comments and sequences of spaces and new lines
+- [`formatHtml()`](ngMocks/formatHtml.md)
 
 * [`flushTestBed()`](ngMocks/flushTestBed.md)
 * [`reset()`](ngMocks/reset.md)

docs/articles/api/ngMocks/crawl.md

@@ -0,0 +1,101 @@
+---
+title: ngMocks.crawl
+description: Documentation about ngMocks.crawl from ng-mocks library
+---
+
+`ngMocks.crawl` is a special function which goes through the passed `DebugNode` or `DebugElement`,
+respects structure `ng-container` and `ng-template` elements,
+and calls a callback function on every item.
+
+`ngMocks.crawl` is used internally by functions which search for desired elements and instances inside of fixtures.
+It is better to use one of them, than this one.
+`ngMocks.crawl` is in shared API in order to give a tool to create some exotic selectors, which are not covered by `ng-mocks`.  
+
+The function accepts  a `DebugNode` or a `DebugElement` as the first parameter,
+and a callback as the second parameter.
+If the callback returns `true`
+then `ngMocks.crawl` stops.
+The callback will receive 2 parameters, the first one is the current `node` and
+the second one is its `parent` if it is present.
+
+There is a special 3rd parameter, in case if you need to include `#text` nodes.
+They are skipped by default, because different versions of angular produce
+a different amount of text nodes for the same template.
+
+```ts
+ngMocks.crawl(debugElement, callback, textNodes);
+```
+
+## Example: first div
+
+A simple example, how we can find a div element.
+Let's assume that the `fixture` points to the root element.
+
+```html
+<section>
+  <div>hello</div>
+</section>
+```
+
+Then in the callback, we can check `nodeName`.
+
+```ts
+// looks for the first div
+ngMocks.crawl(
+  fixture.debugElement,
+  node => {
+    if (node.nativeNode.nodeName === 'DIV') {
+      // do something and stop the walk
+      return true;
+    }
+  },
+);
+```
+
+## Example: direct children of ng-container
+
+Let's assume we want to get all child elements of the first `ng-container`,
+and the `fixture` points to the root element.
+
+```html
+<ng-container>
+  <div>1</div>
+  <div>2</div>
+</ng-container>
+<ng-container>
+  <div>3</div>
+  <div>4</div>
+</ng-container>
+```
+
+Then in the callback we can find `ng-container` and then its children.
+
+```ts
+// let's find the first ng-container
+let ngContainer: any;
+ngMocks.crawl(
+  fixture.debugElement,
+  (node, parent) => {
+    // ng-container is the first element
+    // in our fixture
+    if (parent === fixture.debugElement) {
+        ngContainer = node;
+
+        return true;
+    }
+  },
+);
+
+// let's find its divs
+const divs = [];
+ngMocks.crawl(
+  ngContainer,
+  (node, parent) => {
+    // the same story
+    if (parent === ngContainer) {
+      divs.push(node);
+      // no return because we need all divs
+    }
+  },
+);
+```

docs/articles/api/ngMocks/formatHtml.md

@@ -0,0 +1,84 @@
+---
+title: ngMocks.formatHtml
+description: Documentation about ngMocks.formatHtml from ng-mocks library
+---
+
+`ngMocks.formatHtml` is intended to normalize HTML in order to provide simpler html expectations in tests.
+
+```ts
+const element = document.createElement('div');
+
+// default mode
+ngMocks.formatHtml(element); // empty
+
+// outer mode
+ngMocks.formatHtml(element, true); // <div></div>
+```
+
+`ngMocks.formatHtml` removes:
+- all html comments
+- sequences of spaces, new lines, tabs will be replaced by a single space symbol
+- gaps inside and between siblings is removed, so `<div> </div>` will become `<div></div>`
+
+`ngMocks.formatHtml` accepts:
+- a string
+- `HTMLElement`, `Text`, `Comment`
+- `DebugElement`, `DebugNode`, `ComponentFixture`
+- an array of them
+
+## dirty html
+
+a html like
+
+```html
+<div>
+  <!-- binding1 -->
+  <strong>header</strong>
+  <!-- binding2 -->
+  <ul>
+    <li>1</li>
+    <li>2</li>
+  </ul>
+  <!-- binding3 -->
+</div>
+```
+
+becomes
+
+```html
+<div><strong>header</strong><ul><li>1</li><li>2</li></ul></div>
+```
+
+## ng-container
+
+A cool thing is that `ngMocks.formatHtml` uses [`ngMocks.crawl`](./crawl.md) under the hood
+and respects `ng-container`.
+
+so if we have a pointer to `ng-container`, we can assert its content.
+
+```html
+<div>
+  header
+  <ng-container block1>1</ng-container>
+  body
+  <ng-container block2>2</ng-container>
+  footer
+</div>
+```
+
+```ts
+const div = ngMocks.find('div');
+const block1 = ngMocks.reveal(div, ['block1']);
+const block2 = ngMocks.reveal(div, ['block2']);
+
+ngMocks.formatHtml(div, true);
+// returns
+// <div> headaer 1 body 2 footer </div>
+
+ngMocks.formatHtml(block1);
+// returns
+// 1
+ngMocks.formatHtml(block2);
+// returns
+// 2
+```

docs/articles/api/ngMocks/hide.md

@@ -8,6 +8,7 @@ description: Documentation about ngMocks.hide from ng-mocks library
 ```ts
 ngMocks.hide(declarationInst);
 ngMocks.hide(declarationInst, templateRef);
+ngMocks.hide(declarationInst, debugNode);
 ngMocks.hide(declarationInst, structuralDir);
 ```
 

docs/articles/api/ngMocks/render.md

@@ -14,6 +14,12 @@ ngMocks.render(declarationInst, templateRef, context);
 ngMocks.render(declarationInst, templateRef, context, variables);
 ```
 
+```ts
+ngMocks.render(declarationInst, debugNode);
+ngMocks.render(declarationInst, debugNode, context);
+ngMocks.render(declarationInst, debugNode, context, variables);
+```
+
 ```ts
 ngMocks.render(declarationInst, structuralDir);
 ngMocks.render(declarationInst, structuralDir, context);