|
| 1 | +import type { AST } from 'eslint' |
| 2 | +import type { Comment, Expression, Node } from 'estree' |
| 3 | +import { createRule } from '../utils/createRule.js' |
| 4 | +import { isTestExpression, unwrapExpression } from '../utils/test-expression.js' |
| 5 | + |
| 6 | +/** |
| 7 | + * An ESLint rule that ensures consistent spacing between test blocks (e.g. |
| 8 | + * `test`, `test.step`, `test.beforeEach`, etc.). This rule helps improve the |
| 9 | + * readability and maintainability of test code by ensuring that test blocks are |
| 10 | + * clearly separated from each other. |
| 11 | + */ |
| 12 | +export default createRule({ |
| 13 | + create(context) { |
| 14 | + /** |
| 15 | + * Recursively determines the previous token (if present) and, if necessary, |
| 16 | + * a stand-in token to check spacing against. Therefore, the current start |
| 17 | + * token can optionally be passed through and used as the comparison token. |
| 18 | + * |
| 19 | + * Returns the previous token that is not a comment or a grouping expression |
| 20 | + * (`previous`), the first token to compare (`start`), and the actual token |
| 21 | + * being examined (`origin`). |
| 22 | + * |
| 23 | + * If there is no previous token for the expression, `null` is returned for |
| 24 | + * it. Ideally, the first comparable token is the same as the actual token. |
| 25 | + * |
| 26 | + * | 1 | test('foo', async () => { |
| 27 | + * |
| 28 | + * Previous > | 2 | await test.step(...); | 3 | start > | 4 | // first |
| 29 | + * comment | 5 | // another comment origin > | 6 | await test.step(...); |
| 30 | + */ |
| 31 | + function getPreviousToken( |
| 32 | + node: AST.Token | Node, |
| 33 | + start?: AST.Token | Comment | Node, |
| 34 | + ): { |
| 35 | + /** The token actually being checked */ |
| 36 | + origin: AST.Token | Node |
| 37 | + |
| 38 | + /** |
| 39 | + * The previous token that is neither a comment nor a grouping expression, |
| 40 | + * if present |
| 41 | + */ |
| 42 | + previous: AST.Token | null |
| 43 | + |
| 44 | + /** |
| 45 | + * The first token used for comparison, e.g. the start of the test |
| 46 | + * expression |
| 47 | + */ |
| 48 | + start: AST.Token | Comment | Node |
| 49 | + } { |
| 50 | + const current = start ?? node |
| 51 | + const previous = context.sourceCode.getTokenBefore(current, { |
| 52 | + includeComments: true, |
| 53 | + }) |
| 54 | + |
| 55 | + // no predecessor present |
| 56 | + if ( |
| 57 | + previous === null || |
| 58 | + previous === undefined || |
| 59 | + previous.value === '{' |
| 60 | + ) { |
| 61 | + return { |
| 62 | + origin: node, |
| 63 | + previous: null, |
| 64 | + start: current, |
| 65 | + } |
| 66 | + } |
| 67 | + |
| 68 | + // Recursively traverse comments and determine a stand-in |
| 69 | + // and unwrap parenthesized expressions |
| 70 | + if ( |
| 71 | + previous.type === 'Line' || // line comment |
| 72 | + previous.type === 'Block' || // block comment |
| 73 | + previous.value === '(' // grouping operator |
| 74 | + ) { |
| 75 | + return getPreviousToken(node, previous) |
| 76 | + } |
| 77 | + |
| 78 | + // Return result |
| 79 | + return { |
| 80 | + origin: node, |
| 81 | + previous: previous as AST.Token, |
| 82 | + start: current, |
| 83 | + } |
| 84 | + } |
| 85 | + |
| 86 | + /** |
| 87 | + * Checks whether the spacing before the given test block meets |
| 88 | + * expectations. Optionally an offset token can be provided to check |
| 89 | + * against, for example in the case of an assignment. |
| 90 | + * |
| 91 | + * @param node - The node to be checked. |
| 92 | + * @param offset - Optional offset token to check spacing against. |
| 93 | + */ |
| 94 | + function checkSpacing(node: Expression, offset?: AST.Token | Node) { |
| 95 | + const { previous, start } = getPreviousToken(node, offset) |
| 96 | + |
| 97 | + // First expression or no previous token |
| 98 | + if (previous === null) return |
| 99 | + |
| 100 | + // Ignore when there is one or more blank lines between |
| 101 | + if (previous.loc.end.line < start.loc!.start.line - 1) { |
| 102 | + return |
| 103 | + } |
| 104 | + |
| 105 | + // Since the hint in the IDE may not appear on the affected test expression |
| 106 | + // but possibly on the preceding comment, include the test expression in the message |
| 107 | + const source = context.sourceCode.getText(unwrapExpression(node)) |
| 108 | + |
| 109 | + context.report({ |
| 110 | + data: { source }, |
| 111 | + fix(fixer) { |
| 112 | + return fixer.insertTextAfter(previous, '\n') |
| 113 | + }, |
| 114 | + loc: { |
| 115 | + end: { |
| 116 | + column: start.loc!.start.column, |
| 117 | + line: start.loc!.start.line, |
| 118 | + }, |
| 119 | + start: { |
| 120 | + column: 0, |
| 121 | + line: previous.loc.end.line + 1, |
| 122 | + }, |
| 123 | + }, |
| 124 | + messageId: 'missingWhitespace', |
| 125 | + node, |
| 126 | + }) |
| 127 | + } |
| 128 | + |
| 129 | + return { |
| 130 | + // Checks call expressions that could be test steps, |
| 131 | + // e.g. `test(...)`, `test.step(...)`, or `await test.step(...)`, but also `foo = test(...)` |
| 132 | + ExpressionStatement(node) { |
| 133 | + if (isTestExpression(context, node.expression)) { |
| 134 | + checkSpacing(node.expression) |
| 135 | + } |
| 136 | + }, |
| 137 | + // Checks declarations that might be initialized from return values of test steps, |
| 138 | + // e.g. `let result = await test(...)` or `const result = await test.step(...)` |
| 139 | + VariableDeclaration(node) { |
| 140 | + node.declarations.forEach((declaration) => { |
| 141 | + if (declaration.init && isTestExpression(context, declaration.init)) { |
| 142 | + // When declaring a variable, our examined test expression is used for initialization. |
| 143 | + // Therefore, to check spacing we use the keyword token (let, const, var) before it: |
| 144 | + // 1 | const foo = test('foo', () => {}); |
| 145 | + // 2 | ^ |
| 146 | + const offset = context.sourceCode.getTokenBefore(declaration) |
| 147 | + checkSpacing(declaration.init, offset ?? undefined) |
| 148 | + } |
| 149 | + }) |
| 150 | + }, |
| 151 | + } |
| 152 | + }, |
| 153 | + meta: { |
| 154 | + docs: { |
| 155 | + description: |
| 156 | + 'Enforces a blank line between Playwright test blocks (e.g., test, test.step, test.beforeEach, etc.).', |
| 157 | + recommended: true, |
| 158 | + }, |
| 159 | + fixable: 'whitespace', |
| 160 | + messages: { |
| 161 | + missingWhitespace: |
| 162 | + "A blank line is required before the test block '{{source}}'.", |
| 163 | + }, |
| 164 | + schema: [], |
| 165 | + type: 'layout', |
| 166 | + }, |
| 167 | +}) |
0 commit comments