chore: add toHaveClass partial option

Author: mxschmitt

docs/src/api/class-locatorassertions.md

@@ -1523,6 +1523,12 @@ Expected class or RegExp or a list of those.
 
 Expected class or RegExp or a list of those.
 
+### option: LocatorAssertions.toHaveClass.partial
+* since: v1.52
+- `partial` <[boolean]>
+
+Weather to allow matching a partial class name. Defaults to `false`. By default `toHaveClass` will match the entire `className` attribute.
+
 ### option: LocatorAssertions.toHaveClass.timeout = %%-js-assertions-timeout-%%
 * since: v1.18
 

packages/playwright-core/src/server/injected/injectedScript.ts

@@ -1391,14 +1391,14 @@ export class InjectedScript {
 
     {
       // Single text value.
-      let received: string | undefined;
+      let received: string | string[] | undefined;
       if (expression === 'to.have.attribute.value') {
         const value = element.getAttribute(options.expressionArg);
         if (value === null)
           return { received: null, matches: false };
         received = value;
       } else if (expression === 'to.have.class') {
-        received = element.classList.toString();
+        received = options.expressionArg.partial ? [...element.classList] : element.classList.toString();
       } else if (expression === 'to.have.css') {
         received = this.window.getComputedStyle(element).getPropertyValue(options.expressionArg);
       } else if (expression === 'to.have.id') {
@@ -1443,11 +1443,11 @@ export class InjectedScript {
     }
 
     // List of values.
-    let received: string[] | undefined;
+    let received: (string | string[])[] | undefined;
     if (expression === 'to.have.text.array' || expression === 'to.contain.text.array')
       received = elements.map(e => options.useInnerText ? (e as HTMLElement).innerText : elementText(new Map(), e).full);
     else if (expression === 'to.have.class.array')
-      received = elements.map(e => e.classList.toString());
+      received = elements.map(e => options.expressionArg.partial ? [...e.classList] : e.classList.toString());
 
     if (received && options.expectedText) {
       // "To match an array" is "to contain an array" + "equal length"
@@ -1611,7 +1611,9 @@ class ExpectedTextMatcher {
     }
   }
 
-  matches(text: string): boolean {
+  matches(text: string | string[]): boolean {
+    if (Array.isArray(text))
+      return text.some(t => this.matches(t));
     if (!this._regex)
       text = this.normalize(text)!;
     if (this._string !== undefined)

packages/playwright/src/matchers/matchers.ts

@@ -252,17 +252,18 @@ export function toHaveClass(
   this: ExpectMatcherState,
   locator: LocatorEx,
   expected: string | RegExp | (string | RegExp)[],
-  options?: { timeout?: number },
+  options?: { timeout?: number, partial: boolean },
 ) {
+  const partial = options?.partial;
   if (Array.isArray(expected)) {
     return toEqual.call(this, 'toHaveClass', locator, 'Locator', async (isNot, timeout) => {
       const expectedText = serializeExpectedTextValues(expected);
-      return await locator._expect('to.have.class.array', { expectedText, isNot, timeout });
+      return await locator._expect('to.have.class.array', { expectedText, expressionArg: { partial }, isNot, timeout });
     }, expected, options);
   } else {
     return toMatchText.call(this, 'toHaveClass', locator, 'Locator', async (isNot, timeout) => {
       const expectedText = serializeExpectedTextValues([expected]);
-      return await locator._expect('to.have.class', { expectedText, isNot, timeout });
+      return await locator._expect('to.have.class', { expectedText, expressionArg: { partial }, isNot, timeout });
     }, expected, options);
   }
 }

packages/playwright/types/test.d.ts

@@ -8424,6 +8424,12 @@ interface LocatorAssertions {
    * @param options
    */
   toHaveClass(expected: string|RegExp|ReadonlyArray<string|RegExp>, options?: {
+    /**
+     * Weather to allow matching a partial class name. Defaults to `false`. By default `toHaveClass` will match the entire
+     * `className` attribute.
+     */
+    partial?: boolean;
+
     /**
      * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
      */

tests/page/expect-misc.spec.ts

@@ -220,6 +220,26 @@ test.describe('toHaveClass', () => {
     const error = await expect(locator).toHaveClass(['foo', 'bar', /[a-z]az/], { timeout: 1000 }).catch(e => e);
     expect(error.message).toContain('expect.toHaveClass with timeout 1000ms');
   });
+
+  test('allow matching partial class names', async ({ page }) => {
+    await page.setContent('<div class="foo bar baz"></div>');
+    const locator = page.locator('div');
+    await expect(locator).toHaveClass('foo', { partial: true });
+    await expect(locator).toHaveClass(/f.o/, { partial: true });
+    await expect(locator).not.toHaveClass('foo');
+    await expect(locator).not.toHaveClass('foo', { partial: false });
+  });
+
+  test('allow matching partial class names with array', async ({ page }) => {
+    await page.setContent('<div class="foo f2oo"></div><div class="bar b2ar"></div><div class="bar b2ar"></div>');
+    const locator = page.locator('div');
+    await expect(locator).toHaveClass(['foo', 'b2ar', 'b2ar'], { partial: true });
+    await expect(locator).not.toHaveClass(['foo', 'b2ar', 'b2ar']);
+    await expect(locator).not.toHaveClass(['foo', 'b2ar', /b2?ar/]); // partial allows matching multiple classes
+    await expect(locator).not.toHaveClass(['foo', 'b2ar', 'b2ar'], { partial: false });
+    await expect(locator).not.toHaveClass(['foo', 'b2ar'], { partial: true });
+    await expect(locator).not.toHaveClass(['foo', 'b2ar'], { partial: false });
+  });
 });
 
 test.describe('toHaveTitle', () => {