feat(assertions): support toBeEnabled({ enabled }) (#17058)

docs/src/api/class-locatorassertions.md

@@ -593,6 +593,9 @@ var locator = Page.Locator("button.submit");
 await Expect(locator).toBeEnabledAsync();
 ```
 
+### option: LocatorAssertions.toBeEnabled.enabled
+* since: v1.26
+- `enabled` <[boolean]>
 ### option: LocatorAssertions.toBeEnabled.timeout = %%-js-assertions-timeout-%%
 * since: v1.18
 ### option: LocatorAssertions.toBeEnabled.timeout = %%-csharp-java-python-assertions-timeout-%%

packages/playwright-test/src/matchers/matchers.ts

@@ -78,10 +78,11 @@ export function toBeEmpty(
 export function toBeEnabled(
   this: ReturnType<Expect['getState']>,
   locator: LocatorEx,
-  options?: { timeout?: number },
+  options?: { enabled?: boolean, timeout?: number },
 ) {
   return toBeTruthy.call(this, 'toBeEnabled', locator, 'Locator', async (isNot, timeout, customStackTrace) => {
-    return await locator._expect(customStackTrace, 'to.be.enabled', { isNot, timeout });
+    const enabled = !options || options.enabled === undefined || options.enabled === true;
+    return await locator._expect(customStackTrace, enabled ? 'to.be.enabled' : 'to.be.disabled', { isNot, timeout });
   }, options);
 }
 

packages/playwright-test/types/test.d.ts

@@ -3308,6 +3308,8 @@ interface LocatorAssertions {
    * @param options
    */
   toBeEnabled(options?: {
+    enabled?: boolean;
+
     /**
      * Time to retry the assertion for. Defaults to `timeout` in `TestConfig.expect`.
      */

tests/page/expect-boolean.spec.ts

@@ -84,41 +84,61 @@ test('toBeEditable', async ({ page }) => {
   await expect(locator).toBeEditable();
 });
 
-test('toBeEnabled', async ({ page }) => {
-  await page.setContent('<button>Text</button>');
-  const locator = page.locator('button');
-  await expect(locator).toBeEnabled();
-});
+test.describe('toBeEnabled', () => {
+  test('default', async ({ page }) => {
+    await page.setContent('<button>Text</button>');
+    const locator = page.locator('button');
+    await expect(locator).toBeEnabled();
+  });
 
-test('toBeEnabled failed', async ({ page }) => {
-  await page.setContent('<button disabled>Text</button>');
-  const locator = page.locator('button');
-  const error = await expect(locator).toBeEnabled({ timeout: 1000 }).catch(e => e);
-  expect(error.message).toContain(`selector resolved to <button disabled>Text</button>`);
-});
+  test('with enabled:true', async ({ page }) => {
+    await page.setContent('<button>Text</button>');
+    const locator = page.locator('button');
+    await expect(locator).toBeEnabled({ enabled: true });
+  });
 
-test('toBeEnabled eventually', async ({ page }) => {
-  await page.setContent('<button disabled>Text</button>');
-  const locator = page.locator('button');
-  setTimeout(() => {
-    locator.evaluate(e => e.removeAttribute('disabled')).catch(() => {});
-  }, 500);
-  await expect(locator).toBeEnabled();
-});
+  test('with enabled:false', async ({ page }) => {
+    await page.setContent('<button disabled>Text</button>');
+    const locator = page.locator('button');
+    await expect(locator).toBeEnabled({ enabled: false });
+  });
 
-test('not.toBeEnabled eventually', async ({ page }) => {
-  await page.setContent('<button>Text</button>');
-  const locator = page.locator('button');
-  setTimeout(() => {
-    locator.evaluate(e => e.setAttribute('disabled', '')).catch(() => {});
-  }, 500);
-  await expect(locator).not.toBeEnabled();
-});
+  test('failed', async ({ page }) => {
+    await page.setContent('<button disabled>Text</button>');
+    const locator = page.locator('button');
+    const error = await expect(locator).toBeEnabled({ timeout: 1000 }).catch(e => e);
+    expect(error.message).toContain(`selector resolved to <button disabled>Text</button>`);
+  });
 
-test('toBeDisabled', async ({ page }) => {
-  await page.setContent('<button disabled>Text</button>');
-  const locator = page.locator('button');
-  await expect(locator).toBeDisabled();
+  test('eventually', async ({ page }) => {
+    await page.setContent('<button disabled>Text</button>');
+    const locator = page.locator('button');
+    setTimeout(() => {
+      locator.evaluate(e => e.removeAttribute('disabled')).catch(() => {});
+    }, 500);
+    await expect(locator).toBeEnabled();
+  });
+
+  test('eventually with not', async ({ page }) => {
+    await page.setContent('<button>Text</button>');
+    const locator = page.locator('button');
+    setTimeout(() => {
+      locator.evaluate(e => e.setAttribute('disabled', '')).catch(() => {});
+    }, 500);
+    await expect(locator).not.toBeEnabled();
+  });
+
+  test('with not and enabled:false', async ({ page }) => {
+    await page.setContent('<button>Text</button>');
+    const locator = page.locator('button');
+    await expect(locator).not.toBeEnabled({ enabled: false });
+  });
+
+  test('toBeDisabled', async ({ page }) => {
+    await page.setContent('<button disabled>Text</button>');
+    const locator = page.locator('button');
+    await expect(locator).toBeDisabled();
+  });
 });
 
 test('toBeEmpty input', async ({ page }) => {

tests/playwright-test/expect.spec.ts

@@ -222,6 +222,13 @@ test('should propose only the relevant matchers when custom expect matcher class
       await test.expect(page).not.toBeEnabled();
 
       await test.expect(page.locator('foo')).toBeEnabled();
+      await test.expect(page.locator('foo')).toBeEnabled({ enabled: false });
+      await test.expect(page.locator('foo')).not.toBeEnabled({ enabled: true });
+      // @ts-expect-error
+      await test.expect(page.locator('foo')).toBeEnabled({ unknown: false });
+      // @ts-expect-error
+      await test.expect(page.locator('foo')).toBeEnabled({ enabled: 'foo' });
+
       await test.expect(page.locator('foo')).toBe(true);
       // @ts-expect-error
       await test.expect(page.locator('foo')).toHaveURL('https://example.com');