docs: add docs for DebugElement (#42352)

fixes #36048

PR Close #42352

aio/content/guide/testing-utility-apis.md

@@ -652,7 +652,7 @@ Here are the most useful `DebugElement` members for testers, in approximate orde
       An object that provides parent context for this element.
       Often an ancestor component instance that governs this element.
 
-      When an element is repeated within `*ngFor`, the context is an `NgForRow` whose `$implicit`
+      When an element is repeated within `*ngFor`, the context is an `NgForOf` whose `$implicit`
       property is the value of the row instance value.
       For example, the `hero` in `*ngFor="let hero of heroes"`.
 

packages/core/src/debug/debug_node.ts

@@ -32,13 +32,52 @@ export class DebugEventListener {
  * @publicApi
  */
 export interface DebugNode {
+  /**
+   * The callbacks attached to the component's @Output properties and/or the element's event
+   * properties.
+   */
   readonly listeners: DebugEventListener[];
+
+  /**
+   * The `DebugElement` parent. Will be `null` if this is the root element.
+   */
   readonly parent: DebugElement|null;
+
+  /**
+   * The underlying DOM node.
+   */
   readonly nativeNode: any;
+
+  /**
+   * The host dependency injector. For example, the root element's component instance injector.
+   */
   readonly injector: Injector;
+
+  /**
+   * The element's own component instance, if it has one.
+   */
   readonly componentInstance: any;
+
+  /**
+   * An object that provides parent context for this element. Often an ancestor component instance
+   * that governs this element.
+   *
+   * When an element is repeated within *ngFor, the context is an `NgForOf` whose `$implicit`
+   * property is the value of the row instance value. For example, the `hero` in `*ngFor="let hero
+   * of heroes"`.
+   */
   readonly context: any;
+
+  /**
+   * Dictionary of objects associated with template local variables (e.g. #foo), keyed by the local
+   * variable name.
+   */
   readonly references: {[key: string]: any};
+
+  /**
+   * This component's injector lookup tokens. Includes the component itself plus the tokens that the
+   * component lists in its providers metadata.
+   */
   readonly providerTokens: any[];
 }
 export class DebugNode__PRE_R3__ {
@@ -78,20 +117,101 @@ export class DebugNode__PRE_R3__ {
 
 /**
  * @publicApi
+ *
+ * @see [Component testing scenarios](guide/testing-components-scenarios)
+ * @see [Basics of testing components](guide/testing-components-basics)
+ * @see [Testing utility APIs](guide/testing-utility-apis)
  */
 export interface DebugElement extends DebugNode {
+  /**
+   * The element tag name, if it is an element.
+   */
   readonly name: string;
+
+  /**
+   *  A map of property names to property values for an element.
+   *
+   *  This map includes:
+   *  - Regular property bindings (e.g. `[id]="id"`)
+   *  - Host property bindings (e.g. `host: { '[id]': "id" }`)
+   *  - Interpolated property bindings (e.g. `id="{{ value }}")
+   *
+   *  It does not include:
+   *  - input property bindings (e.g. `[myCustomInput]="value"`)
+   *  - attribute bindings (e.g. `[attr.role]="menu"`)
+   */
   readonly properties: {[key: string]: any};
+
+  /**
+   *  A map of attribute names to attribute values for an element.
+   */
   readonly attributes: {[key: string]: string|null};
+
+  /**
+   * A map containing the class names on the element as keys.
+   *
+   * This map is derived from the `className` property of the DOM element.
+   *
+   * Note: The values of this object will always be `true`. The class key will not appear in the KV
+   * object if it does not exist on the element.
+   *
+   * @see [Element.className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className)
+   */
   readonly classes: {[key: string]: boolean};
+
+  /**
+   * The inline styles of the DOM element.
+   *
+   * Will be `null` if there is no `style` property on the underlying DOM element.
+   *
+   * @see [ElementCSSInlineStyle](https://developer.mozilla.org/en-US/docs/Web/API/ElementCSSInlineStyle/style)
+   */
   readonly styles: {[key: string]: string|null};
+
+  /**
+   * The `childNodes` of the DOM element as a `DebugNode` array.
+   *
+   * @see [Node.childNodes](https://developer.mozilla.org/en-US/docs/Web/API/Node/childNodes)
+   */
   readonly childNodes: DebugNode[];
+
+  /**
+   * The underlying DOM element at the root of the component.
+   */
   readonly nativeElement: any;
+
+  /**
+   * The immediate `DebugElement` children. Walk the tree by descending through `children`.
+   */
   readonly children: DebugElement[];
 
+  /**
+   * @returns the first `DebugElement` that matches the predicate at any depth in the subtree.
+   */
   query(predicate: Predicate<DebugElement>): DebugElement;
+
+  /**
+   * @returns All `DebugElement` matches for the predicate at any depth in the subtree.
+   */
   queryAll(predicate: Predicate<DebugElement>): DebugElement[];
+
+  /**
+   * @returns All `DebugNode` matches for the predicate at any depth in the subtree.
+   */
   queryAllNodes(predicate: Predicate<DebugNode>): DebugNode[];
+
+  /**
+   * Triggers the event by its name if there is a corresponding listener in the element's
+   * `listeners` collection.
+   *
+   * If the event lacks a listener or there's some other problem, consider
+   * calling `nativeElement.dispatchEvent(eventObject)`.
+   *
+   * @param eventName The name of the event to trigger
+   * @param eventObj The _event object_ expected by the handler
+   *
+   * @see [Testing components scenarios](guide/testing-components-scenarios#trigger-event-handler)
+   */
   triggerEventHandler(eventName: string, eventObj: any): void;
 }
 export class DebugElement__PRE_R3__ extends DebugNode__PRE_R3__ implements DebugElement {