From 62b5a6cb079e489d91982abe88d644d73feb73f3 Mon Sep 17 00:00:00 2001 From: Andrew Scott Date: Tue, 25 May 2021 14:26:42 -0700 Subject: [PATCH] docs: add docs for DebugElement (#42352) fixes #36048 PR Close #42352 --- aio/content/guide/testing-utility-apis.md | 2 +- packages/core/src/debug/debug_node.ts | 120 ++++++++++++++++++++++ 2 files changed, 121 insertions(+), 1 deletion(-) diff --git a/aio/content/guide/testing-utility-apis.md b/aio/content/guide/testing-utility-apis.md index 1f4628bc9f..286804ecb0 100644 --- a/aio/content/guide/testing-utility-apis.md +++ b/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"`. diff --git a/packages/core/src/debug/debug_node.ts b/packages/core/src/debug/debug_node.ts index f5db218fac..3177456a68 100644 --- a/packages/core/src/debug/debug_node.ts +++ b/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; + + /** + * @returns All `DebugElement` matches for the predicate at any depth in the subtree. + */ queryAll(predicate: Predicate): DebugElement[]; + + /** + * @returns All `DebugNode` matches for the predicate at any depth in the subtree. + */ queryAllNodes(predicate: Predicate): 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 {