docs: clarify toBeDisabled behavior (#13616)

docs/src/api/class-locatorassertions.md

@@ -337,7 +337,11 @@ await Expect(locator).ToBeCheckedAsync();
 * langs:
   - alias-java: isDisabled
 
-Ensures the [Locator] points to a disabled element.
+Ensures the [Locator] points to a disabled element. Element is disabled if it has "disabled" attribute
+or is disabled via ['aria-disabled'](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-disabled).
+Note that only native control elements such as HTML `button`, `input`, `select`, `textarea`, `option`, `optgroup`
+can be disabled by setting "disabled" attribute. "disabled" attribute on other elements is ignored
+by the browser.
 
 ```js
 const locator = page.locator('button.submit');

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

@@ -3163,7 +3163,10 @@ interface LocatorAssertions {
   }): Promise<void>;
 
   /**
-   * Ensures the [Locator] points to a disabled element.
+   * Ensures the [Locator] points to a disabled element. Element is disabled if it has "disabled" attribute or is disabled
+   * via ['aria-disabled'](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-disabled). Note
+   * that only native control elements such as HTML `button`, `input`, `select`, `textarea`, `option`, `optgroup` can be
+   * disabled by setting "disabled" attribute. "disabled" attribute on other elements is ignored by the browser.
    *
    * ```js
    * const locator = page.locator('button.submit');

tests/config/experimental.d.ts

@@ -19368,7 +19368,10 @@ interface LocatorAssertions {
   }): Promise<void>;
 
   /**
-   * Ensures the [Locator] points to a disabled element.
+   * Ensures the [Locator] points to a disabled element. Element is disabled if it has "disabled" attribute or is disabled
+   * via ['aria-disabled'](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-disabled). Note
+   * that only native control elements such as HTML `button`, `input`, `select`, `textarea`, `option`, `optgroup` can be
+   * disabled by setting "disabled" attribute. "disabled" attribute on other elements is ignored by the browser.
    *
    * ```js
    * const locator = page.locator('button.submit');

tests/playwright-test/playwright.expect.true.spec.ts

@@ -176,6 +176,39 @@ test('should support toBeEditable, toBeEnabled, toBeDisabled, toBeEmpty', async
   expect(output).toContain('expect(locator).toBeEnabled({ timeout: 500 }');
 });
 
+test('should support toBeDisabled,toBeChecked,toBeHidden w/ value', async ({ runInlineTest }) => {
+  const result = await runInlineTest({
+    'a.test.ts': `
+      const { test } = pwt;
+
+      test('disabled', async ({ page }) => {
+        await page.setContent('<button disabled="yes">Text</button>');
+        const locator = page.locator('button');
+        await expect(locator).toBeDisabled();
+      });
+      test('checked', async ({ page }) => {
+        await page.setContent('<input type=checkbox checked="yes"></input>');
+        const locator = page.locator('input');
+        await expect(locator).toBeChecked();
+      });
+      test('hidden', async ({ page }) => {
+        await page.setContent('<input type=checkbox hidden="of course"></input>');
+        const locator = page.locator('input');
+        await expect(locator).toBeHidden();
+      });
+      test('div disabled', async ({ page }) => {
+        await page.setContent('<div disabled="yes"></div>');
+        const locator = page.locator('div');
+        await expect(locator).not.toBeDisabled();
+      });
+      `,
+  }, { workers: 1 });
+  expect(result.passed).toBe(4);
+  expect(result.failed).toBe(0);
+  expect(result.exitCode).toBe(0);
+});
+
+
 test('should support toBeVisible, toBeHidden', async ({ runInlineTest }) => {
   const result = await runInlineTest({
     'a.test.ts': `