feat: add custom missing await rule (#4)

Author: mskelton

.github/workflows/test.yml

@@ -0,0 +1,20 @@
+name: Test
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [12.x, 14.x, 16.x]
+    steps:
+      - uses: actions/checkout@v2
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v1
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm ci
+      - run: npm test

.gitignore

@@ -0,0 +1 @@
+node_modules/

README.md

@@ -1,29 +1,61 @@
-# ESLint Jest Playwright globals
+# ESLint Jest Playwright
 
-> ESLint globals for your [Jest](https://jestjs.io/) [Playwright](https://github.com/microsoft/playwright) ([jest-playwright](https://github.com/mmarkelov/jest-playwright/)) installation.
+> ESLint plugin for your [Jest](https://jestjs.io/) [Playwright](https://github.com/microsoft/playwright) ([jest-playwright](https://github.com/mmarkelov/jest-playwright/)) installation.
+
+## Installation
+
+Yarn
+
+```txt
+yarn add -D eslint-plugin-jest-playwright
+```
+
+NPM
+
+```txt
+npm install -D eslint-plugin-jest-playwright
+```
 
 ## Usage
 
 Add `plugin:jest-playwright/recommended` to your extends ESLint configuration. For example:
 
 ```json
 {
-    "extends": [
-        "plugin:jest-playwright/recommended"
-    ]
+  "extends": ["plugin:jest-playwright/recommended"],
+  "plugins": ["jest-playwright"]
 }
 ```
 
-## Installation
+## Rules
 
-Yarn
+### `missing-playwright-expect` 🔧
 
-```txt
-yarn add -D eslint-plugin-jest-playwright
+Enforce Jest Playwright expect statements to be awaited.
+
+#### Example
+
+Example of **incorrect** code for this rule:
+
+```js
+expect(page).toHaveText("text");
 ```
 
-NPM
+Example of **correct** code for this rule:
 
-```txt
-npm install -D eslint-plugin-jest-playwright
+```js
+await expect(page).toHaveText("text");
+```
+
+#### Options
+
+The rule accepts a non-required option which can be used to specify custom matchers which this rule should also warn about. This is useful when creating your own async matchers.
+
+```json
+{
+  "jest-playwright/missing-playwright-await": [
+    "error",
+    { "customMatchers": ["toHaveAttribute"] }
+  ]
+}
 ```

index.js

@@ -0,0 +1,39 @@
+const missingPlaywrightAwait = require("./rules/missing-playwright-await");
+
+module.exports = {
+  configs: {
+    recommended: {
+      env: {
+        "shared-node-browser": true,
+        jest: true,
+      },
+      rules: {
+        "jest-playwright/missing-playwright-await": "error",
+        "jest/no-standalone-expect": [
+          "error",
+          {
+            additionalTestBlockFunctions: [
+              "test.jestPlaywrightDebug",
+              "it.jestPlaywrightDebug",
+              "test.jestPlaywrightSkip",
+              "it.jestPlaywrightSkip",
+              "test.jestPlaywrightConfig",
+              "it.jestPlaywrightConfig",
+            ],
+          },
+        ],
+      },
+      globals: {
+        browserName: true,
+        deviceName: true,
+        browser: true,
+        context: true,
+        page: true,
+        jestPlaywright: true,
+      },
+    },
+  },
+  rules: {
+    "missing-playwright-await": missingPlaywrightAwait,
+  },
+};

lib/index.js

@@ -0,0 +1,69 @@
+function getPromiseMemberExpressionNode(node, matchers) {
+  if (node.property.type === "Identifier" && matchers.has(node.property.name)) {
+    return node;
+  }
+}
+
+function isValidExpect(node) {
+  const parentType =
+    node.parent && node.parent.parent && node.parent.parent.type;
+
+  // Don't report on nodes which are already awaited or returned
+  return parentType === "AwaitExpression" || parentType === "ReturnStatement";
+}
+
+module.exports = {
+  create(context) {
+    const options = context.options[0] || {};
+    const matchers = new Set([
+      "toHaveSelector",
+      "toHaveSelectorCount",
+      "toHaveText",
+      "toEqualText",
+      "toEqualValue",
+      "toEqualUrl",
+      "toHaveFocus",
+      // Add any custom matchers to the set
+      ...(options.customMatchers || []),
+    ]);
+
+    return {
+      MemberExpression(statement) {
+        const node = getPromiseMemberExpressionNode(statement, matchers);
+        if (!node || isValidExpect(node)) return;
+
+        context.report({
+          fix(fixer) {
+            return fixer.insertTextBefore(node, "await ");
+          },
+          messageId: "missingAwait",
+          node,
+        });
+      },
+    };
+  },
+  meta: {
+    docs: {
+      category: "Possible Errors",
+      description: "Enforce Jest Playwright expect statements to be awaited.",
+      recommended: true,
+    },
+    fixable: "code",
+    messages: {
+      missingAwait: "Playwright expectations must be awaited or returned.",
+    },
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          customMatchers: {
+            items: { type: "string" },
+            type: "array",
+          },
+        },
+        type: "object",
+      },
+    ],
+    type: "problem",
+  },
+};