feat(material-experimental): add option to filter checkbox harnesses by name

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)

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,17 @@ 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 there is no way for
+        // developers to query the checkbox harness by CSS selector.
+        .addOption('name', options.name, async (harness, name) => await harness.getName() === name);
   }
 
   private _label = this.locatorFor('.mat-checkbox-label');
@@ -64,22 +69,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,17 @@ 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 there is no way for
+        // developers to query the checkbox harness by CSS selector.
+        .addOption('name', options.name, async (harness, name) => await harness.getName() === name);
   }
 
   private _label = this.locatorFor('label');
@@ -64,22 +69,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');
   }