feat(material/testing): Add 'label' filter to form field control

harnesses

This facilitates testing by making it possible to fetch certain
harnesses using their floating label text (mat-label). Previously, the
user would have to locate the harness using an id or class, or by
calling MatFormFieldHarness.getControl().

This affects the following harnesses:
- MatInputHarness
- MatSelectHarness
- MatNativeSelectHarness
- MatDatepickerInputHarness
- MatDateRangeInputHarness

Tests via unit tests

Author: wildcardalice

src/material/datepicker/testing/date-range-input-harness.spec.ts

@@ -11,6 +11,7 @@ import {
   MatEndDate,
   MatStartDate,
 } from '../../datepicker';
+import {MatFormFieldModule} from '../../form-field';
 import {MatCalendarHarness} from './calendar-harness';
 import {
   MatDateRangeInputHarness,
@@ -34,7 +35,14 @@ describe('matDateRangeInputHarness', () => {
 
   it('should load all date range input harnesses', async () => {
     const inputs = await loader.getAllHarnesses(MatDateRangeInputHarness);
-    expect(inputs.length).toBe(2);
+    expect(inputs.length).toBe(3);
+  });
+
+  it('should load date range input with a specific label', async () => {
+    const inputs = await loader.getAllHarnesses(
+      MatDateRangeInputHarness.with({label: 'Date range'}),
+    );
+    expect(inputs.length).toBe(1);
   });
 
   it('should get whether the input is disabled', async () => {
@@ -261,13 +269,22 @@ describe('matDateRangeInputHarness', () => {
       <input matStartDate>
       <input matEndDate>
     </mat-date-range-input>
+
+    <mat-form-field>
+      <mat-label>Date range</mat-label>
+      <mat-date-range-input basic>
+      <input matStartDate>
+      <input matEndDate>
+    </mat-date-range-input>
+    </mat-form-field>
   `,
   imports: [
     MatNativeDateModule,
     MatDateRangeInput,
     MatStartDate,
     MatEndDate,
     MatDateRangePicker,
+    MatFormFieldModule,
     FormsModule,
   ],
 })

src/material/datepicker/testing/date-range-input-harness.ts

@@ -48,6 +48,8 @@ export class MatEndDateHarness extends MatDatepickerInputHarnessBase {
 export class MatDateRangeInputHarness extends DatepickerTriggerHarnessBase {
   static hostSelector = '.mat-date-range-input';
 
+  private readonly floatingLabelSelector = '.mdc-floating-label';
+
   /**
    * Gets a `HarnessPredicate` that can be used to search for a `MatDateRangeInputHarness`
    * that meets certain criteria.
@@ -57,11 +59,13 @@ export class MatDateRangeInputHarness extends DatepickerTriggerHarnessBase {
   static with(
     options: DateRangeInputHarnessFilters = {},
   ): HarnessPredicate<MatDateRangeInputHarness> {
-    return new HarnessPredicate(MatDateRangeInputHarness, options).addOption(
-      'value',
-      options.value,
-      (harness, value) => HarnessPredicate.stringMatches(harness.getValue(), value),
-    );
+    return new HarnessPredicate(MatDateRangeInputHarness, options)
+      .addOption('value', options.value, (harness, value) =>
+        HarnessPredicate.stringMatches(harness.getValue(), value),
+      )
+      .addOption('label', options.label, (harness, label) => {
+        return HarnessPredicate.stringMatches(harness.getLabel(), label);
+      });
   }
 
   /** Gets the combined value of the start and end inputs, including the separator. */
@@ -87,6 +91,31 @@ export class MatDateRangeInputHarness extends DatepickerTriggerHarnessBase {
     return this.locatorFor(MatEndDateHarness)();
   }
 
+  /** Gets the floating label text for the range input, if it exists. */
+  async getLabel(): Promise<string | null> {
+    // Copied from MatFormFieldControlHarness since this class cannot extend two classes
+    const documentRootLocator = await this.documentRootLocatorFactory();
+    const labelId = await (await this.host()).getAttribute('aria-labelledby');
+    const hostId = await (await this.host()).getAttribute('id');
+
+    if (labelId) {
+      // First option, try to fetch the label using the `aria-labelledby`
+      // attribute.
+      const labelEl = await await documentRootLocator.locatorForOptional(
+        `${this.floatingLabelSelector}[id="${labelId}"]`,
+      )();
+      return labelEl ? labelEl.text() : null;
+    } else if (hostId) {
+      // Fallback option, try to match the id of the input with the `for`
+      // attribute of the label.
+      const labelEl = await await documentRootLocator.locatorForOptional(
+        `${this.floatingLabelSelector}[for="${hostId}"]`,
+      )();
+      return labelEl ? labelEl.text() : null;
+    }
+    return null;
+  }
+
   /** Gets the separator text between the values of the two inputs. */
   async getSeparator(): Promise<string> {
     return (await this.locatorFor('.mat-date-range-input-separator')()).text();

src/material/datepicker/testing/datepicker-harness-filters.ts

@@ -6,10 +6,11 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
+import {MatFormFieldControlHarnessFilters} from '@angular/material/form-field/testing/control';
 import {BaseHarnessFilters} from '@angular/cdk/testing';
 
 /** A set of criteria that can be used to filter a list of datepicker input instances. */
-export interface DatepickerInputHarnessFilters extends BaseHarnessFilters {
+export interface DatepickerInputHarnessFilters extends MatFormFieldControlHarnessFilters {
   /** Filters based on the value of the input. */
   value?: string | RegExp;
   /** Filters based on the placeholder text of the input. */
@@ -43,7 +44,7 @@ export interface CalendarCellHarnessFilters extends BaseHarnessFilters {
 }
 
 /** A set of criteria that can be used to filter a list of date range input instances. */
-export interface DateRangeInputHarnessFilters extends BaseHarnessFilters {
+export interface DateRangeInputHarnessFilters extends MatFormFieldControlHarnessFilters {
   /** Filters based on the value of the input. */
   value?: string | RegExp;
 }

src/material/datepicker/testing/datepicker-input-harness-base.ts

@@ -7,7 +7,7 @@
  */
 
 import {ComponentHarnessConstructor, HarnessPredicate} from '@angular/cdk/testing';
-import {MatFormFieldControlHarness} from '../../form-field/testing/control';
+import {MatFormFieldControlHarness} from '@angular/material/form-field/testing/control';
 import {DatepickerInputHarnessFilters} from './datepicker-harness-filters';
 
 /** Sets up the filter predicates for a datepicker input harness. */
@@ -21,6 +21,9 @@ export function getInputPredicate<T extends MatDatepickerInputHarnessBase>(
     })
     .addOption('placeholder', options.placeholder, (harness, placeholder) => {
       return HarnessPredicate.stringMatches(harness.getPlaceholder(), placeholder);
+    })
+    .addOption('label', options.label, (harness, label) => {
+      return HarnessPredicate.stringMatches(harness.getLabel(), label);
     });
 }
 
@@ -36,6 +39,11 @@ export abstract class MatDatepickerInputHarnessBase extends MatFormFieldControlH
     return (await this.host()).getProperty<boolean>('required');
   }
 
+  /** Gets the floating label text for the input, if it exists. */
+  async getLabel(): Promise<string | null> {
+    return await this._getFloatingLabelText();
+  }
+
   /** Gets the value of the input. */
   async getValue(): Promise<string> {
     // The "value" property of the native input is always defined.

src/material/datepicker/testing/datepicker-input-harness.spec.ts

@@ -5,6 +5,8 @@ import {ComponentFixture, TestBed} from '@angular/core/testing';
 import {FormsModule} from '@angular/forms';
 import {DateAdapter, MATERIAL_ANIMATIONS, MatNativeDateModule} from '../../core';
 import {MatDatepickerModule} from '../../datepicker';
+import {MatFormFieldModule} from '../../form-field';
+import {MatInputModule} from '../../input';
 import {MatCalendarHarness} from './calendar-harness';
 import {MatDatepickerInputHarness} from './datepicker-input-harness';
 
@@ -27,6 +29,13 @@ describe('MatDatepickerInputHarness', () => {
     expect(inputs.length).toBe(2);
   });
 
+  it('should load datepicker input with a specific label', async () => {
+    const selects = await loader.getAllHarnesses(
+      MatDatepickerInputHarness.with({label: 'Pick a date'}),
+    );
+    expect(selects.length).toBe(1);
+  });
+
   it('should filter inputs based on their value', async () => {
     fixture.componentInstance.date = new Date(2020, 0, 1, 12, 0, 0);
     fixture.changeDetectorRef.markForCheck();
@@ -187,21 +196,31 @@ describe('MatDatepickerInputHarness', () => {
 
 @Component({
   template: `
-    <input
-      id="basic"
-      matInput
-      [matDatepicker]="picker"
-      (dateChange)="dateChangeCount = dateChangeCount + 1"
-      [(ngModel)]="date"
-      [min]="minDate"
-      [max]="maxDate"
-      [disabled]="disabled"
-      [required]="required"
-      placeholder="Type a date">
-    <mat-datepicker #picker [touchUi]="touchUi"></mat-datepicker>
+    <mat-form-field>
+      <mat-label>Pick a date</mat-label>
+      <input
+        id="basic"
+        matInput
+        [matDatepicker]="picker"
+        (dateChange)="dateChangeCount = dateChangeCount + 1"
+        [(ngModel)]="date"
+        [min]="minDate"
+        [max]="maxDate"
+        [disabled]="disabled"
+        [required]="required"
+        placeholder="Type a date">
+      <mat-datepicker #picker [touchUi]="touchUi"></mat-datepicker>
+    </mat-form-field>
+
     <input id="no-datepicker" matDatepicker>
   `,
-  imports: [MatNativeDateModule, MatDatepickerModule, FormsModule],
+  imports: [
+    MatNativeDateModule,
+    MatDatepickerModule,
+    MatFormFieldModule,
+    MatInputModule,
+    FormsModule,
+  ],
 })
 class DatepickerInputHarnessTest {
   date: Date | null = null;

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

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import {BaseHarnessFilters} from '@angular/cdk/testing';
+
+/**
+ * A set of criteria shared by any class derived from `MatFormFieldControlHarness`, that can be
+ * used to filter a list of those components.
+ */
+export interface MatFormFieldControlHarnessFilters extends BaseHarnessFilters {
+  /** Filters based on the text of the form field's floating label. */
+  label?: string | RegExp;
+}

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

@@ -12,4 +12,30 @@ import {ComponentHarness} from '@angular/cdk/testing';
  * Base class for custom form-field control harnesses. Harnesses for
  * custom controls with form-fields need to implement this interface.
  */
-export abstract class MatFormFieldControlHarness extends ComponentHarness {}
+export abstract class MatFormFieldControlHarness extends ComponentHarness {
+  private readonly floatingLabelSelector = '.mdc-floating-label';
+
+  /** Gets the text content of the floating label, if it exists. */
+  protected async _getFloatingLabelText(): Promise<string | null> {
+    const documentRootLocator = await this.documentRootLocatorFactory();
+    const labelId = await (await this.host()).getAttribute('aria-labelledby');
+    const hostId = await (await this.host()).getAttribute('id');
+
+    if (labelId) {
+      // First option, try to fetch the label using the `aria-labelledby`
+      // attribute.
+      const labelEl = await await documentRootLocator.locatorForOptional(
+        `${this.floatingLabelSelector}[id="${labelId}"]`,
+      )();
+      return labelEl ? labelEl.text() : null;
+    } else if (hostId) {
+      // Fallback option, try to match the id of the input with the `for`
+      // attribute of the label.
+      const labelEl = await await documentRootLocator.locatorForOptional(
+        `${this.floatingLabelSelector}[for="${hostId}"]`,
+      )();
+      return labelEl ? labelEl.text() : null;
+    }
+    return null;
+  }
+}

src/material/form-field/testing/control/index.ts

@@ -7,3 +7,4 @@
  */
 
 export * from './form-field-control-harness';
+export * from './form-field-control-harness-filters';

src/material/input/testing/input-harness-filters.ts

@@ -6,10 +6,10 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import {BaseHarnessFilters} from '@angular/cdk/testing';
+import {MatFormFieldControlHarnessFilters} from '@angular/material/form-field/testing/control';
 
 /** A set of criteria that can be used to filter a list of `MatInputHarness` instances. */
-export interface InputHarnessFilters extends BaseHarnessFilters {
+export interface InputHarnessFilters extends MatFormFieldControlHarnessFilters {
   /** Filters based on the value of the input. */
   value?: string | RegExp;
   /** Filters based on the placeholder text of the input. */

src/material/input/testing/input-harness.spec.ts

@@ -39,6 +39,11 @@ describe('MatInputHarness', () => {
     expect(inputs.length).toBe(1);
   });
 
+  it('should load input with a specific label', async () => {
+    const inputs = await loader.getAllHarnesses(MatInputHarness.with({label: 'Favorite food'}));
+    expect(inputs.length).toBe(1);
+  });
+
   it('should load input with a value that matches a regex', async () => {
     const inputs = await loader.getAllHarnesses(MatInputHarness.with({value: /shi$/}));
     expect(inputs.length).toBe(1);
@@ -231,6 +236,7 @@ describe('MatInputHarness', () => {
 @Component({
   template: `
     <mat-form-field>
+      <mat-label>Favorite food</mat-label>
       <input matInput placeholder="Favorite food" value="Sushi" name="favorite-food">
     </mat-form-field>
 

src/material/input/testing/input-harness.ts

@@ -7,12 +7,14 @@
  */
 
 import {HarnessPredicate, parallel} from '@angular/cdk/testing';
-import {MatFormFieldControlHarness} from '../../form-field/testing/control';
+import {MatFormFieldControlHarness} from '@angular/material/form-field/testing/control';
 import {coerceBooleanProperty} from '@angular/cdk/coercion';
 import {InputHarnessFilters} from './input-harness-filters';
 
 /** Harness for interacting with a standard Material inputs in tests. */
 export class MatInputHarness extends MatFormFieldControlHarness {
+  private readonly _documentRootLocator = this.documentRootLocatorFactory();
+
   // TODO: We do not want to handle `select` elements with `matNativeControl` because
   // not all methods of this harness work reasonably for native select elements.
   // For more details. See: https://github.com/angular/components/pull/18221.
@@ -31,6 +33,9 @@ export class MatInputHarness extends MatFormFieldControlHarness {
       })
       .addOption('placeholder', options.placeholder, (harness, placeholder) => {
         return HarnessPredicate.stringMatches(harness.getPlaceholder(), placeholder);
+      })
+      .addOption('label', options.label, (harness, label) => {
+        return HarnessPredicate.stringMatches(harness.getLabel(), label);
       });
   }
 
@@ -94,6 +99,11 @@ export class MatInputHarness extends MatFormFieldControlHarness {
     return await (await this.host()).getProperty<string>('id');
   }
 
+  /** Gets the floating label text for the input, if it exists. */
+  async getLabel(): Promise<string | null> {
+    return await this._getFloatingLabelText();
+  }
+
   /**
    * Focuses the input and returns a promise that indicates when the
    * action is complete.

src/material/input/testing/native-select-harness-filters.ts

@@ -7,9 +7,10 @@
  */
 
 import {BaseHarnessFilters} from '@angular/cdk/testing';
+import {MatFormFieldControlHarnessFilters} from '@angular/material/form-field/testing/control';
 
 /** A set of criteria that can be used to filter a list of `MatNativeSelectHarness` instances. */
-export interface NativeSelectHarnessFilters extends BaseHarnessFilters {}
+export interface NativeSelectHarnessFilters extends MatFormFieldControlHarnessFilters {}
 
 /** A set of criteria that can be used to filter a list of `MatNativeOptionHarness` instances. */
 export interface NativeOptionHarnessFilters extends BaseHarnessFilters {

src/material/input/testing/native-select-harness.spec.ts

@@ -21,6 +21,13 @@ describe('MatNativeSelectHarness', () => {
     expect(selects.length).toBe(2);
   });
 
+  it('should load select with a specific label', async () => {
+    const inputs = await loader.getAllHarnesses(
+      MatNativeSelectHarness.with({label: 'Favorite food'}),
+    );
+    expect(inputs.length).toBe(1);
+  });
+
   it('should get the id of a select', async () => {
     const selects = await loader.getAllHarnesses(MatNativeSelectHarness);
     expect(await parallel(() => selects.map(select => select.getId()))).toEqual(['food', 'drink']);
@@ -187,6 +194,7 @@ describe('MatNativeSelectHarness', () => {
 @Component({
   template: `
     <mat-form-field>
+      <mat-label>Favorite food</mat-label>
       <select
         id="food"
         matNativeControl