feat(material-experimental): add option to filter checkbox har… (#16662)

Adds an option to the checkbox harnesses that allows developers
to filter harnesses by checkbox names. This is helpful because
developers can not filter checkboxes by name using CSS selectors
because the `name` input binding is not bound to the host DOM element.

Similar to #16609 (comment)

(cherry picked from commit 2cbabf0)

Author: devversion

src/material-experimental/mdc-checkbox/harness/checkbox-harness-filters.ts

@@ -7,5 +7,6 @@
  */
 
 export type CheckboxHarnessFilters = {
-  label?: string | RegExp
+  label?: string|RegExp;
+  name?: string;
 };

src/material-experimental/mdc-checkbox/harness/checkbox-harness.spec.ts

@@ -15,10 +15,12 @@ let checkboxHarness: typeof MatCheckboxHarness;
 describe('MatCheckboxHarness', () => {
   describe('non-MDC-based', () => {
     beforeEach(async () => {
-      await TestBed.configureTestingModule({
-        imports: [MatCheckboxModule, ReactiveFormsModule],
-        declarations: [CheckboxHarnessTest],
-      }).compileComponents();
+      await TestBed
+          .configureTestingModule({
+            imports: [MatCheckboxModule, ReactiveFormsModule],
+            declarations: [CheckboxHarnessTest],
+          })
+          .compileComponents();
 
       fixture = TestBed.createComponent(CheckboxHarnessTest);
       fixture.detectChanges();
@@ -31,10 +33,12 @@ describe('MatCheckboxHarness', () => {
 
   describe('MDC-based', () => {
     beforeEach(async () => {
-      await TestBed.configureTestingModule({
-        imports: [MatMdcCheckboxModule, ReactiveFormsModule],
-        declarations: [CheckboxHarnessTest],
-      }).compileComponents();
+      await TestBed
+          .configureTestingModule({
+            imports: [MatMdcCheckboxModule, ReactiveFormsModule],
+            declarations: [CheckboxHarnessTest],
+          })
+          .compileComponents();
 
       fixture = TestBed.createComponent(CheckboxHarnessTest);
       fixture.detectChanges();
@@ -61,6 +65,12 @@ function runTests() {
     expect(await checkboxes[0].getLabelText()).toBe('First');
   });
 
+  it('should load checkbox with name', async () => {
+    const checkboxes = await loader.getAllHarnesses(checkboxHarness.with({name: 'first-name'}));
+    expect(checkboxes.length).toBe(1);
+    expect(await checkboxes[0].getLabelText()).toBe('First');
+  });
+
   it('should load checkbox with regex label match', async () => {
     const checkboxes = await loader.getAllHarnesses(checkboxHarness.with({label: /^s/i}));
     expect(checkboxes.length).toBe(1);
@@ -199,4 +209,3 @@ class CheckboxHarnessTest {
   ctrl = new FormControl(true);
   disabled = true;
 }
-

src/material-experimental/mdc-checkbox/harness/checkbox-harness.ts

@@ -21,12 +21,18 @@ export class MatCheckboxHarness extends ComponentHarness {
    * Gets a `HarnessPredicate` that can be used to search for a checkbox with specific attributes.
    * @param options Options for narrowing the search:
    *   - `label` finds a checkbox with specific label text.
+   *   - `name` finds a checkbox with specific name.
    * @return a `HarnessPredicate` configured with the given options.
    */
   static with(options: CheckboxHarnessFilters = {}): HarnessPredicate<MatCheckboxHarness> {
     return new HarnessPredicate(MatCheckboxHarness)
-        .addOption('label', options.label,
-            (harness, label) => HarnessPredicate.stringMatches(harness.getLabelText(), label));
+        .addOption(
+            'label', options.label,
+            (harness, label) => HarnessPredicate.stringMatches(harness.getLabelText(), label))
+        // We want to provide a filter option for "name" because the name of the checkbox is
+        // only set on the underlying input. This means that it's not possible for developers
+        // to retrieve the harness of a specific checkbox with name through a CSS selector.
+        .addOption('name', options.name, async (harness, name) => await harness.getName() === name);
   }
 
   private _label = this.locatorFor('.mat-checkbox-label');
@@ -64,22 +70,22 @@ export class MatCheckboxHarness extends ComponentHarness {
   }
 
   /** Gets a promise for the checkbox's name. */
-  async getName(): Promise<string | null> {
+  async getName(): Promise<string|null> {
     return (await this._input()).getAttribute('name');
   }
 
   /** Gets a promise for the checkbox's value. */
-  async getValue(): Promise<string | null> {
+  async getValue(): Promise<string|null> {
     return (await this._input()).getAttribute('value');
   }
 
   /** Gets a promise for the checkbox's aria-label. */
-  async getAriaLabel(): Promise<string | null> {
+  async getAriaLabel(): Promise<string|null> {
     return (await this._input()).getAttribute('aria-label');
   }
 
   /** Gets a promise for the checkbox's aria-labelledby. */
-  async getAriaLabelledby(): Promise<string | null> {
+  async getAriaLabelledby(): Promise<string|null> {
     return (await this._input()).getAttribute('aria-labelledby');
   }
 

src/material-experimental/mdc-checkbox/harness/mdc-checkbox-harness.ts

@@ -21,12 +21,18 @@ export class MatCheckboxHarness extends ComponentHarness {
    * Gets a `HarnessPredicate` that can be used to search for a checkbox with specific attributes.
    * @param options Options for narrowing the search:
    *   - `label` finds a checkbox with specific label text.
+   *   - `name` finds a checkbox with specific name.
    * @return a `HarnessPredicate` configured with the given options.
    */
   static with(options: CheckboxHarnessFilters = {}): HarnessPredicate<MatCheckboxHarness> {
     return new HarnessPredicate(MatCheckboxHarness)
-        .addOption('label', options.label,
-            (harness, label) => HarnessPredicate.stringMatches(harness.getLabelText(), label));
+        .addOption(
+            'label', options.label,
+            (harness, label) => HarnessPredicate.stringMatches(harness.getLabelText(), label))
+        // We want to provide a filter option for "name" because the name of the checkbox is
+        // only set on the underlying input. This means that it's not possible for developers
+        // to retrieve the harness of a specific checkbox with name through a CSS selector.
+        .addOption('name', options.name, async (harness, name) => await harness.getName() === name);
   }
 
   private _label = this.locatorFor('label');
@@ -64,22 +70,22 @@ export class MatCheckboxHarness extends ComponentHarness {
   }
 
   /** Gets a promise for the checkbox's name. */
-  async getName(): Promise<string | null> {
+  async getName(): Promise<string|null> {
     return (await this._input()).getAttribute('name');
   }
 
   /** Gets a promise for the checkbox's value. */
-  async getValue(): Promise<string | null> {
+  async getValue(): Promise<string|null> {
     return (await this._input()).getAttribute('value');
   }
 
   /** Gets a promise for the checkbox's aria-label. */
-  async getAriaLabel(): Promise<string | null> {
+  async getAriaLabel(): Promise<string|null> {
     return (await this._input()).getAttribute('aria-label');
   }
 
   /** Gets a promise for the checkbox's aria-labelledby. */
-  async getAriaLabelledby(): Promise<string | null> {
+  async getAriaLabelledby(): Promise<string|null> {
     return (await this._input()).getAttribute('aria-labelledby');
   }