docs: ✏️ byTestId DOM selector (#726)

* docs: ✏️ add byTestId DOM selector

* test: 💍 add missing byTestId tests

Author: chimurai

docs/docs/queries.md

@@ -44,6 +44,7 @@ spectator.query(byText('By text'));
 spectator.query(byText('By text', {selector: '#some .selector'}));
 spectator.query(byTextContent('By text content', {selector: '#some .selector'}));
 spectator.query(byRole('checkbox', { checked: true }));
+spectator.query(byTestId('someTestId'))
 ```
 
 The difference between `byText` and `byTextContent` is that the former doesn't match text inside a nested elements.
@@ -64,6 +65,14 @@ expect(byPlaceholder('Please enter your email address')).toHaveValue('my-value')
 // ... See the Custom Matchers section for a full list of possible matchers
 ```
 
+Configure `@testing-library/dom` to use `byTestId` with a different `testIdAttribute`
+
+```ts
+import { configure } from '@testing-library/dom';
+
+configure({ testIdAttribute: 'data-test' });
+```
+
 ### Parent Selector
 Spectator allows you to query for nested elements within a parent element. This is useful when you have multiple instances of the same component on the page and you want to query for children within a specific one. The parent selector is a string selector that is used to find the parent element. The parent selector is passed as the second parameter to the query methods. For example:
 ```ts

projects/spectator/jest/test/dom-selectors/dom-selectors.component.spec.ts

@@ -8,7 +8,9 @@ import {
   byTitle,
   byValue,
   byTextContent,
+  byTestId,
 } from '@ngneat/spectator/jest';
+import { configure, getConfig } from '@testing-library/dom';
 
 import { DomSelectorsComponent, DomSelectorsNestedComponent } from '../../../test/dom-selectors/dom-selectors.component';
 
@@ -170,4 +172,23 @@ describe('DomSelectorsComponent', () => {
       });
     });
   });
+
+  describe('byTestId', () => {
+    const { testIdAttribute } = getConfig();
+    beforeEach(() => configure({ testIdAttribute }));
+    afterEach(() => configure({ testIdAttribute }));
+
+    it('should allow querying with byTestId (default: data-testid)', () => {
+      const element = spectator.query(byTestId('by-testid-default'));
+      expect(element).toHaveAttribute('data-testid', 'by-testid-default');
+    });
+
+    it('should allow querying with byTestId and custom testIdAttribute', () => {
+      // configure byTestId to use the custom attribute
+      configure({ testIdAttribute: 'data-testid-custom' });
+
+      const element = spectator.query(byTestId('by-testid-custom'));
+      expect(element).toHaveAttribute('data-testid-custom', 'by-testid-custom');
+    });
+  });
 });

projects/spectator/test/dom-selectors/dom-selectors.component.spec.ts

@@ -2,6 +2,7 @@ import {
   byAltText,
   byLabel,
   byPlaceholder,
+  byTestId,
   byText,
   byTextContent,
   byTitle,
@@ -10,6 +11,7 @@ import {
   createComponentFactory,
   Spectator,
 } from '@ngneat/spectator';
+import { configure, getConfig } from '@testing-library/dom';
 
 import { DomSelectorsComponent, DomSelectorsNestedComponent } from './dom-selectors.component';
 
@@ -216,4 +218,23 @@ describe('DomSelectorsComponent', () => {
       expect(element).toHaveExactText('Sugar');
     });
   });
+
+  describe('byTestId', () => {
+    const { testIdAttribute } = getConfig();
+    beforeEach(() => configure({ testIdAttribute }));
+    afterEach(() => configure({ testIdAttribute }));
+
+    it('should allow querying with byTestId (default: data-testid)', () => {
+      const element = spectator.query(byTestId('by-testid-default'));
+      expect(element).toHaveAttribute('data-testid', 'by-testid-default');
+    });
+
+    it('should allow querying with byTestId and custom testIdAttribute', () => {
+      // configure byTestId to use the custom attribute
+      configure({ testIdAttribute: 'data-testid-custom' });
+
+      const element = spectator.query(byTestId('by-testid-custom'));
+      expect(element).toHaveAttribute('data-testid-custom', 'by-testid-custom');
+    });
+  });
 });

projects/spectator/test/dom-selectors/dom-selectors.component.ts

@@ -52,6 +52,11 @@ export class DomSelectorsNestedComponent {}
       <app-dom-selectors-nested-components id="first"></app-dom-selectors-nested-components>
       <app-dom-selectors-nested-components id="last"></app-dom-selectors-nested-components>
     </div>
+
+    <div id="testid">
+      <div data-testid="by-testid-default"></div>
+      <div data-testid-custom="by-testid-custom"></div>
+    </div>
   `,
   standalone: false,
   imports: [DomSelectorsNestedComponent],

projects/spectator/vitest/test/dom-selectors/dom-selectors.component.spec.ts

@@ -8,7 +8,9 @@ import {
   byTitle,
   byValue,
   byTextContent,
+  byTestId,
 } from '@ngneat/spectator/vitest';
+import { configure, getConfig } from '@testing-library/dom';
 
 import { DomSelectorsComponent, DomSelectorsNestedComponent } from '../../../test/dom-selectors/dom-selectors.component';
 
@@ -170,4 +172,23 @@ describe('DomSelectorsComponent', () => {
       });
     });
   });
+
+  describe('byTestId', () => {
+    const { testIdAttribute } = getConfig();
+    beforeEach(() => configure({ testIdAttribute }));
+    afterEach(() => configure({ testIdAttribute }));
+
+    it('should allow querying with byTestId (default: data-testid)', () => {
+      const element = spectator.query(byTestId('by-testid-default'));
+      expect(element).toHaveAttribute('data-testid', 'by-testid-default');
+    });
+
+    it('should allow querying with byTestId and custom testIdAttribute', () => {
+      // configure byTestId to use the custom attribute
+      configure({ testIdAttribute: 'data-testid-custom' });
+
+      const element = spectator.query(byTestId('by-testid-custom'));
+      expect(element).toHaveAttribute('data-testid-custom', 'by-testid-custom');
+    });
+  });
 });