refactor(form-field/testing): deprecate methods that return TestElement (#19940)

In general we want to avoid exposing `TestElement` instances in the public harness API. These changes mark `getHarnessLoaderForSuffix` and `getHarnessLoaderForPrefix` as deprecated since they don't do what their names say and they're exposing a `TestElement`. I've added replacements that return the text of the elements since that's what appears to be the main use case.

Author: crisbeto

src/material-experimental/mdc-form-field/testing/form-field-harness.ts

@@ -160,19 +160,35 @@ export class MatFormFieldHarness extends ComponentHarness {
   /**
    * Gets a reference to the container element which contains all projected
    * prefixes of the form-field.
+   * @deprecated Use `getPrefixText` instead.
+   * @breaking-change 11.0.0
    */
   async getHarnessLoaderForPrefix(): Promise<TestElement|null> {
     return this._prefixContainer();
   }
 
+  /** Gets the text inside the prefix element. */
+  async getPrefixText(): Promise<string> {
+    const prefix = await this._prefixContainer();
+    return prefix ? prefix.text() : '';
+  }
+
   /**
    * Gets a reference to the container element which contains all projected
    * suffixes of the form-field.
+   * @deprecated Use `getSuffixText` instead.
+   * @breaking-change 11.0.0
    */
   async getHarnessLoaderForSuffix(): Promise<TestElement|null> {
     return this._suffixContainer();
   }
 
+  /** Gets the text inside the suffix element. */
+  async getSuffixText(): Promise<string> {
+    const suffix = await this._suffixContainer();
+    return suffix ? suffix.text() : '';
+  }
+
   /**
    * Whether the form control has been touched. Returns "null"
    * if no form control is set up.

src/material/form-field/testing/form-field-harness.ts

@@ -165,19 +165,35 @@ export class MatFormFieldHarness extends ComponentHarness {
   /**
    * Gets a reference to the container element which contains all projected
    * prefixes of the form-field.
+   * @deprecated Use `getPrefixText` instead.
+   * @breaking-change 11.0.0
    */
   async getHarnessLoaderForPrefix(): Promise<TestElement|null> {
     return this._prefixContainer();
   }
 
+  /** Gets the text inside the prefix element. */
+  async getPrefixText(): Promise<string> {
+    const prefix = await this._prefixContainer();
+    return prefix ? prefix.text() : '';
+  }
+
   /**
    * Gets a reference to the container element which contains all projected
    * suffixes of the form-field.
+   * @deprecated Use `getSuffixText` instead.
+   * @breaking-change 11.0.0
    */
   async getHarnessLoaderForSuffix(): Promise<TestElement|null> {
     return this._suffixContainer();
   }
 
+  /** Gets the text inside the suffix element. */
+  async getSuffixText(): Promise<string> {
+    const suffix = await this._suffixContainer();
+    return suffix ? suffix.text() : '';
+  }
+
   /**
    * Whether the form control has been touched. Returns "null"
    * if no form control is set up.

src/material/form-field/testing/shared.spec.ts

@@ -188,20 +188,16 @@ export function runHarnessTests(
     expect(await formFields[1].getTextHints()).toEqual([]);
   });
 
-  it('should be able to get prefix container of form-field', async () => {
+  it('should be able to get the prefix text of a form-field', async () => {
     const formFields = await loader.getAllHarnesses(formFieldHarness);
-    const prefixContainers = await Promise.all(formFields.map(f => f.getHarnessLoaderForPrefix()));
-    expect(prefixContainers[0]).not.toBe(null);
-    expect(await prefixContainers[0]!.text()).toBe('prefix_textprefix_text_2');
-    expect(prefixContainers[1]).toBe(null);
+    const prefixTexts = await Promise.all(formFields.map(f => f.getPrefixText()));
+    expect(prefixTexts).toEqual(['prefix_textprefix_text_2', '', '', '', '']);
   });
 
-  it('should be able to get suffix container of form-field', async () => {
+  it('should be able to get the suffix text of a form-field', async () => {
     const formFields = await loader.getAllHarnesses(formFieldHarness);
-    const suffixContainer = await Promise.all(formFields.map(f => f.getHarnessLoaderForSuffix()));
-    expect(suffixContainer[0]).not.toBe(null);
-    expect(await suffixContainer[0]!.text()).toBe('suffix_text');
-    expect(suffixContainer[1]).toBe(null);
+    const suffixTexts = await Promise.all(formFields.map(f => f.getSuffixText()));
+    expect(suffixTexts).toEqual(['suffix_text', '', '', '', '']);
   });
 
   it('should be able to check if form field has been touched', async () => {

tools/public_api_guard/material/form-field/testing.d.ts

@@ -13,6 +13,8 @@ export declare class MatFormFieldHarness extends ComponentHarness {
     getHarnessLoaderForPrefix(): Promise<TestElement | null>;
     getHarnessLoaderForSuffix(): Promise<TestElement | null>;
     getLabel(): Promise<string | null>;
+    getPrefixText(): Promise<string>;
+    getSuffixText(): Promise<string>;
     getTextErrors(): Promise<string[]>;
     getTextHints(): Promise<string[]>;
     getThemeColor(): Promise<'primary' | 'accent' | 'warn'>;