Subchapter 127.3

Scan Cypress

const lineOf

const suppressed

This file

Number: 127.3
Position: 3 of 3
Type: JavaScript
Size: 23 KB
Lines: 506

Nearby

Previous Removed Apis

Source

scripts/scan-cypress.mjs

JavaScript506 lines23 KB

1#!/usr/bin/env node
2// Scan Cypress specs, support files, and config for flake-prone anti-patterns
3// and for APIs removed in Cypress 12 through 16.
4//
5// Zero dependencies. Requires Node.js 18 or later.
6// The scan is heuristic (text based, no AST). Treat findings as leads to
7// confirm in the code, not as proof.
8
9import fs from 'node:fs'
10import path from 'node:path'
11import process from 'node:process'
12
13const

scan-cypress.mjs on GitHub

HELP

=

`Usage: node scan-cypress.mjs [paths...] [options]

Scans Cypress test code for flake-prone anti-patterns and removed APIs.

With no path, scans the current directory.

Options:

--json Print machine-readable JSON instead of text

--strict Also report low-confidence rules (CY1xx)

--rule <ids> Only report these rule ids, comma separated (CY001,CY005)

--max-per-rule <n> Findings listed per rule in text output (default 20, 0 = all)

--fail-on <level> Exit 1 if a finding at this level or above exists:

error | warn | info | never (default never)

--cypress-major <n> Override the Cypress major version detected from package.json

--list-rules Print the rule catalog and exit

-h, --help Show this help

Suppress a finding with a comment on the same or the previous line:

// cy-scan-ignore (all rules)

// cy-scan-ignore CY001 (one or more rule ids)

Exit codes: 0 ok, 1 threshold from --fail-on reached, 2 usage or I/O error.`

const RULES = {

CY001: ['fixed-wait', 'warn', 'cy.wait(<number>) waits on time. Wait on a cy.intercept() alias or a retrying assertion.'],

CY002: ['assigned-return-value', 'error', 'A cy command return value is assigned. Commands are queued and yield later; use .then(), .should(), or an alias.'],

CY003: ['async-await', 'error', 'async/await is used with Cypress commands. Commands are not promises; remove async and await.'],

CY004: ['force-true', 'warn', '{ force: true } skips actionability checks. Find what covers or disables the element.'],

CY005: ['chain-after-action', 'warn', 'A command is chained after an action. Safe only if the element cannot re-render; otherwise start a new cy.get().'],

CY006: ['one-shot-assertion', 'warn', 'expect() inside .then() runs once and does not retry. Use .should() or .should(callback).'],

CY007: ['removed-api', 'error', 'API removed or changed in a newer Cypress major.'],

CY008: ['conditional-on-dom', 'warn', 'Test branches on DOM state. Make the state deterministic, then assert it.'],

CY009: ['exclusive-or-debug', 'warn', '.only, cy.pause(), or cy.debug() left in the code.'],

CY010: ['cleanup-in-after-hook', 'info', 'State is cleaned in after/afterEach. Reset state in before/beforeEach so interrupted runs do not leak.'],

CY011: ['absolute-local-visit', 'info', 'cy.visit() uses an absolute local URL. Set baseUrl and visit a relative path.'],

CY012: ['ui-login-without-session', 'info', 'Password is typed through the UI in several files and cy.session() is never used.'],

CY013: ['positional-selector', 'info', 'Selector depends on element position. Prefer a data-* attribute.'],

CY101: ['brittle-selector', 'info', 'Selector relies on a CSS class or id. Prefer a data-* attribute.'],

CY102: ['negative-assertion-as-wait', 'info', 'A negative assertion passes before the element has rendered. Confirm a positive state was asserted first.'],

CY103: ['variable-wait', 'info', 'cy.wait() is called with an identifier. Confirm it is an alias, not a number of milliseconds.'],

}

const LEVELS = { info: 1, warn: 2, error: 3 }

const REMOVED = [

[/\bCypress\s*\.\s*env\s*\(/g, 16, 'Cypress.env() was removed in 16.0 (deprecated 15.10). Use cy.env([...]) for secrets or Cypress.expose() for public values.'],

[/\bcy\s*\.\s*exec\s*\(/g, 16, 'cy.exec() was removed in 16.0. Register a task in setupNodeEvents and call cy.task().'],

[/\)\s*\.\s*end\s*$\s*$/g, 16, '.end() was removed in 16.0. Delete the call.'],

[/\bexecTimeout\b/g, 16, 'execTimeout was removed in 16.0 with cy.exec(). Use taskTimeout.'],

[/\bexperimentalMemoryManagement\b/g, 16, 'experimentalMemoryManagement was removed in 16.0. Delete it, or set manageBrowserMemory: false to opt out.'],

[/\bexperimentalFastVisibility\b/g, 16, 'experimentalFastVisibility was removed in 16.0. visibilityStrategy defaults to "modern".'],

[/\bexperimentalSourceRewriting\b/g, 16, 'experimentalSourceRewriting was removed in 16.0. Delete it; use removeSRIAttributes for SRI errors.'],

[/\ballowCypressEnv\b/g, 16, 'allowCypressEnv was removed in 16.0. Delete it.'],

[/\bCypress\s*\.\s*config\s*\(\s*['"`](?:viewportWidth|viewportHeight|blockHosts)['"`]\s*,/g, 16, 'Setting this through Cypress.config() during a test throws in 16.0. Use cy.viewport() or the test config object.'],

[/\bCypress\s*\.\s*Commands\s*\.\s*overwrite\s*\(\s*['"`](?:getCookie|getCookies|getAllCookies|getAllLocalStorage|getAllSessionStorage)['"`]/g, 16, 'This command is a query in 16.0. Use Cypress.Commands.overwriteQuery().'],

[/\bCypress\s*\.\s*SelectorPlayground\b/g, 15, 'Cypress.SelectorPlayground was renamed Cypress.ElementSelector in 15.0.'],

[/\bexperimentalSkipDomainInjection\b/g, 14, 'experimentalSkipDomainInjection was removed in 14.0. Use cy.origin() for subdomains.'],

[/\bexperimentalJustInTimeCompile\b/g, 14, 'experimentalJustInTimeCompile became justInTimeCompile in 14.0.'],

[/\bvideoUploadOnPasses\b/g, 13, 'videoUploadOnPasses was removed in 13.0.'],

[/\bcy\s*\.\s*(?:server|route)\s*\(/g, 12, 'cy.server() and cy.route() were removed in 12.0. Use cy.intercept().'],

[/\bCypress\s*\.\s*Cookies\s*\.\s*(?:preserveOnce|defaults)\b/g, 12, 'Cypress.Cookies.preserveOnce() and .defaults() were removed in 12.0. Use cy.session().'],

[/\bexperimentalSessionAndOrigin\b/g, 12, 'experimentalSessionAndOrigin was removed in 12.0. cy.session() and cy.origin() are stable.'],

[/\bcy\s*\.\s*route2\s*\(/g, 7, 'cy.route2() was renamed cy.intercept() in 7.0.'],

[/\bcy\s*\.\s*xpath\s*\(/g, null, 'cy.xpath() comes from the deprecated cypress-xpath plugin. Use cy.get() or cy.contains().'],

]

const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'coverage', '.next', '.nuxt', 'out', 'screenshots', 'videos', 'downloads'])

const CODE_EXT = /\.(?:[cm]?[jt]sx?)$/

function rel(file) {

const relative = path.relative(process.cwd(), file)

const shown = relative && !relative.startsWith('..') && !path.isAbsolute(relative) ? relative : file

return shown.split(path.sep).join('/')

}

function fail(message) {

process.stderr.write(`scan-cypress: ${message}\n`)

process.exit(2)

}

function parseArgs(argv) {

const opts = { paths: [], json: false, strict: false, rules: null, maxPerRule: 20, failOn: 'never', major: undefined }

for (let i = 0; i < argv.length; i++) {

const arg = argv[i]

const next = () => {

if (i + 1 >= argv.length) fail(`${arg} needs a value`)

return argv[++i]

}

if (arg === '-h' || arg === '--help') { process.stdout.write(`${HELP}\n`); process.exit(0) }

else if (arg === '--list-rules') {

for (const [id, [name, level, text]] of Object.entries(RULES)) process.stdout.write(`${id} ${name.padEnd(28)} ${level.padEnd(5)} ${text}\n`)

process.exit(0)

}

else if (arg === '--json') opts.json = true

else if (arg === '--strict') opts.strict = true

else if (arg === '--rule') opts.rules = new Set(next().split(',').map((s) => s.trim().toUpperCase()).filter(Boolean))

else if (arg === '--max-per-rule') {

opts.maxPerRule = Number(next())

if (!Number.isInteger(opts.maxPerRule) || opts.maxPerRule < 0) fail('--max-per-rule needs a non-negative integer')

}

else if (arg === '--fail-on') {

opts.failOn = next()

if (!['error', 'warn', 'info', 'never'].includes(opts.failOn)) fail('--fail-on must be error, warn, info, or never')

}

else if (arg === '--cypress-major') {

opts.major = Number(next())

if (!Number.isInteger(opts.major) || opts.major < 1) fail('--cypress-major needs a positive integer')

}

else if (arg.startsWith('-')) fail(`unknown option ${arg} (try --help)`)

else opts.paths.push(arg)

}

if (opts.paths.length === 0) opts.paths.push('.')

if (opts.rules) for (const id of opts.rules) if (!RULES[id]) fail(`unknown rule ${id} (try --list-rules)`)

return opts

}

function isCypressFile(file) {

const normalized = rel(file)

const base = path.basename(normalized)

if (/^cypress\.config\.[cm]?[jt]s$/.test(base)) return true

if (!CODE_EXT.test(base)) return false

if (/\.cy\.[cm]?[jt]sx?$/.test(base)) return true

return /(?:^|\/)cypress\//.test(normalized)

}

function walk(target, files, coffee) {

let stat

try { stat = fs.statSync(target) } catch { fail(`cannot read ${target}`) }

if (stat.isFile()) {

if (isCypressFile(target) || CODE_EXT.test(target)) files.push(target)

return

}

for (const entry of fs.readdirSync(target, { withFileTypes: true })) {

const full = path.join(target, entry.name)

if (entry.isDirectory()) {

if (!SKIP_DIRS.has(entry.name)) walk(full, files, coffee)

} else if (entry.isFile()) {

if (isCypressFile(full)) files.push(full)

else if (/\.coffee$/.test(entry.name) && /(?:^|\/)cypress\//.test(full.split(path.sep).join('/'))) coffee.push(full)

}

function detectCypress(startDir) {

let dir = path.resolve(startDir)

for (let depth = 0; depth < 8; depth++) {

const file = path.join(dir, 'package.json')

if (fs.existsSync(file)) {

try {

const pkg = JSON.parse(fs.readFileSync(file, 'utf8'))

const range = pkg.devDependencies?.cypress ?? pkg.dependencies?.cypress

if (range) {

const match = String(range).match(/\d+/)

return { range: String(range), major: match ? Number(match[0]) : null, source: file }

}

} catch { /* unreadable package.json: keep walking up */ }

}

const parent = path.dirname(dir)

if (parent === dir) break

dir = parent

}

return { range: null, major: null, source: null }

}

// Replace comments with spaces so offsets and line numbers stay valid.

function blankComments(src) {

let out = ''

let state = 'code'

for (let i = 0; i < src.length;) {

const c = src[i]

const d = src[i + 1]

if (state === 'code') {

if (c === '\\') { out += c + (d ?? ''); i += 2; continue }

if (c === '/' && d === '/') { state = 'line'; out += ' '; i += 2; continue }

if (c === '/' && d === '*') { state = 'block'; out += ' '; i += 2; continue }

if (c === "'") state = 'sq'

else if (c === '"') state = 'dq'

else if (c === '`') state = 'tpl'

out += c; i++; continue

}

if (state === 'line') {

if (c === '\n') { state = 'code'; out += c } else out += ' '

i++; continue

}

if (state === 'block') {

if (c === '*' && d === '/') { state = 'code'; out += ' '; i += 2; continue }

out += c === '\n' ? '\n' : ' '

i++; continue

}

if (c === '\\') { out += c + (d ?? ''); i += 2; continue }

if ((state === 'sq' && c === "'") || (state === 'dq' && c === '"') || (state === 'tpl' && c === '`')) state = 'code'

else if ((state === 'sq' || state === 'dq') && c === '\n') state = 'code'

out += c; i++

}

return out

}

// Index of the parenthesis that closes the one at `open`, or -1.

function matchParen(src, open) {

let depth = 0

let quote = null

for (let i = open; i < src.length; i++) {

const c = src[i]

if (quote) {

if (c === '\\') { i++; continue }

if (c === quote) quote = null

continue

}

if (c === "'" || c === '"' || c === '`') { quote = c; continue }

if (c === '(') depth++

else if (c === ')') { depth--; if (depth === 0) return i }

}

return -1

}

// Start offset of the statement whose chain contains offset `idx`.

function chainStart(src, idx) {

let depth = 0

for (let j = idx - 1; j >= 0; j--) {

const c = src[j]

if (c === ')' || c === ']' || c === '}') depth++

else if (c === '(' || c === '[' || c === '{') {

if (depth === 0) return j + 1

depth--

} else if (depth === 0) {

if (c === ';') return j + 1

if (c === '\n') {

const rest = src.slice(j + 1, idx).trimStart()

if (rest && rest[0] !== '.') return j + 1

}

return 0

}

function countTopLevelCommas(args) {

let depth = 0

let quote = null

let commas = 0

for (let i = 0; i < args.length; i++) {

const c = args[i]

if (quote) {

if (c === '\\') { i++; continue }

if (c === quote) quote = null

continue

}

if (c === "'" || c === '"' || c === '`') quote = c

else if (c === '(' || c === '[' || c === '{') depth++

else if (c === ')' || c === ']' || c === '}') depth--

else if (c === ',' && depth === 0 && args.slice(i + 1).trim()) commas++

}

return commas

}

function scanFile(file, opts, major, findings) {

const raw = fs.readFileSync(file, 'utf8')

const rawLines = raw.split('\n')

const src = blankComments(raw)

const lineStarts = [0]

for (let i = 0; i < src.length; i++) if (src[i] === '\n') lineStarts.push(i + 1)

const lineOf = (offset) => {

let lo = 0

let hi = lineStarts.length - 1

while (lo < hi) {

const mid = (lo + hi + 1) >> 1

if (lineStarts[mid] <= offset) lo = mid

else hi = mid - 1

}

return lo + 1

}

const suppressed = (line, rule) => {

for (const text of [rawLines[line - 1], rawLines[line - 2]]) {

const match = text?.match(/cy-scan-ignore\b([^\n]*)/)

if (!match) continue

const ids = match[1].match(/CY\d{3}/g)

if (!ids || ids.includes(rule)) return true

}

return false

}

const add = (rule, offset, message, level) => {

if (opts.rules && !opts.rules.has(rule)) return

if (!opts.strict && /^CY1\d\d$/.test(rule) && !(opts.rules && opts.rules.has(rule))) return

const line = lineOf(offset)

if (suppressed(line, rule)) return

const snippet = (rawLines[line - 1] ?? '').trim()

findings.push({

rule,

name: RULES[rule][0],

level: level ?? RULES[rule][1],

file: rel(file),

line,

message: message ?? RULES[rule][2],

snippet: snippet.length > 140 ? `${snippet.slice(0, 137)}...` : snippet,

})

}

const each = (regex, fn) => {

regex.lastIndex = 0

let match

while ((match = regex.exec(src)) !== null) {

fn(match)

if (match[0].length === 0) regex.lastIndex++

}

// CY001 fixed waits

each(/(?:\bcy|\))\s*\.\s*wait\s*\(\s*\d[\d_.]*\s*[,)]/g, (m) => add('CY001', m.index + m[0].indexOf('wait')))

// CY103 wait on an identifier (strict)

each(/\bcy\s*\.\s*wait\s*$\s*[A-Za-z_$][\w$.]*\s*$/g, (m) => add('CY103', m.index))

// CY002 assigned return values. cy.stub() and cy.spy() are synchronous and exempt.

each(/\b(?:const|let|var)\s+[^=;\n]+=\s*cy\s*\.\s*(\w+)/g, (m) => {

if (!['stub', 'spy', 'state'].includes(m[1])) add('CY002', m.index)

})

// CY003 async tests and awaited commands

each(/\b(?:it|specify|before|beforeEach|after|afterEach)(?:\s*\.\s*(?:only|skip))?\s*\(\s*(?:(['"`])(?:\\.|(?!\1)[^\\])*\1\s*,\s*)?(?:\{[^{}]*(?:\{[^{}]*\}[^{}]*)*\}\s*,\s*)?async\b/g, (m) => add('CY003', m.index))

each(/\bawait\s+cy\s*\./g, (m) => add('CY003', m.index, 'A cy command is awaited. Commands are not promises; use .then().'))

// CY004 force

each(/\bforce\s*:\s*true\b/g, (m) => add('CY004', m.index))

// CY005 chaining after an action

each(new RegExp(`\\.\\s*(${ACTIONS})\\s*\\(`, 'g'), (m) => {

const open = m.index + m[0].length - 1

const close = matchParen(src, open)

if (close === -1) return

const tail = src.slice(close + 1).match(/^\s*\.\s*([A-Za-z_$][\w$]*)/)

if (!tail) return

const next = tail[1]

if (['then', 'as', 'catch', 'finally', 'end'].includes(next)) return

const start = chainStart(src, m.index)

if (!/^\s*(?:return\s+)?cy\b/.test(src.slice(start, m.index))) return

const soft = next === 'should' || next === 'and'

add(

'CY005',

m.index,

soft

? `.${next}() is chained after .${m[1]}(). If the action re-renders the element the subject is stale; re-query before asserting.`

: `.${next}() is chained after .${m[1]}(). Start a new cy.get() unless the element cannot re-render.`,

soft ? 'info' : 'warn',

)

})

// CY006 expect() inside .then() after a DOM or page query

each(/\.\s*then\s*\(/g, (m) => {

const open = m.index + m[0].length - 1

const close = matchParen(src, open)

if (close === -1) return

const body = src.slice(open + 1, close)

if (!/\bexpect\s*\(|\bassert\s*[.(]/.test(body) || /\bcy\s*\./.test(body)) return

const chain = src.slice(chainStart(src, m.index), m.index)

if (!/^\s*(?:return\s+)?cy\b/.test(chain)) return

if (/\bcy\s*\.\s*get\s*\(\s*['"`]@/.test(chain)) return

add('CY006', m.index)

})

// CY007 removed APIs

for (const [regex, removedIn, text] of REMOVED) {

each(regex, (m) => {

const broken = removedIn === null ? false : major === null ? null : major >= removedIn

const level = broken === true ? 'error' : 'warn'

const suffix = removedIn === null || major === null ? '' : broken ? ` Installed major is ${major}: this already fails.` : ` Installed major is ${major}: fix before upgrading.`

add('CY007', m.index, `${text}${suffix}`, level)

})

}

each(/\bcy\s*\.\s*stub\s*\(/g, (m) => {

const open = m.index + m[0].length - 1

const close = matchParen(src, open)

if (close === -1) return

if (countTopLevelCommas(src.slice(open + 1, close)) >= 2) {

const broken = major !== null && major >= 15

add('CY007', m.index, 'cy.stub(obj, name, fn) was removed in 15.0. Use cy.stub(obj, name).callsFake(fn).', broken ? 'error' : 'warn')

}

})

// CY008 conditional testing

// CY009 exclusive tests and debug commands

each(/\b(?:it|describe|context|specify)\s*\.\s*only\s*\(/g, (m) => add('CY009', m.index, '.only is committed: the rest of the suite does not run.'))

each(/(?:\bcy|\))\s*\.\s*(?:pause|debug)\s*$\s*$/g, (m) => add('CY009', m.index, 'cy.pause() or cy.debug() left in the code.'))

// CY010 cleanup hooks

each(/(?:^|\n)[ \t]*(?:after|afterEach)\s*\(/g, (m) => add('CY010', m.index + m[0].search(/a/)))

// CY011 absolute local visit

each(/\bcy\s*\.\s*visit\s*\(\s*['"`]https?:\/\/(?:localhost|127\.0\.0\.1|0\.0\.0\.0)/g, (m) => add('CY011', m.index))

// CY013 and CY101 selectors

each(/(?:\bcy\s*\.\s*get|\.\s*find)\s*\(\s*(['"`])((?:\\.|(?!\1)[^\\\n])*)\1/g, (m) => {

const selector = m[2]

if (selector.startsWith('@') || selector.includes('${')) return

else if (!/\[data-|\[aria-|\[role=|\[name=/.test(selector) && /(?:^|[\s>+~])[.#][\w-]+/.test(selector)) add('CY101', m.index)

})

// CY102 negative assertions

each(/\.\s*should\s*$\s*['"`]not\.(?:exist|be\.visible)['"`]\s*$/g, (m) => add('CY102', m.index))

return {

typesPassword: /(?:password|passwd|pwd)[^\n]{0,80}\.\s*type\s*\(|type\s*=\s*["']?password/i.test(src),

usesSession: /\bcy\s*\.\s*session\s*\(/.test(src),

}

function main() {

const opts = parseArgs(process.argv.slice(2))

const files = []

const coffee = []

for (const target of opts.paths) walk(target, files, coffee)

const unique = [...new Set(files)].sort()

const firstPath = opts.paths[0]

const startDir = fs.statSync(firstPath).isDirectory() ? firstPath : path.dirname(firstPath)

const detected = detectCypress(startDir)

const major = opts.major ?? detected.major

const findings = []

const passwordFiles = []

let sessionUsed = false

for (const file of unique) {

const facts = scanFile(file, opts, major, findings)

if (facts.typesPassword) passwordFiles.push(rel(file))

if (facts.usesSession) sessionUsed = true

}

const wants = (rule) => !opts.rules || opts.rules.has(rule)

if (wants('CY012') && !sessionUsed && passwordFiles.length >= 2) {

findings.push({

rule: 'CY012', name: RULES.CY012[0], level: RULES.CY012[1], file: passwordFiles[0], line: 1,

message: `${RULES.CY012[2]} Files: ${passwordFiles.slice(0, 8).join(', ')}${passwordFiles.length > 8 ? ', ...' : ''}`,

snippet: '',

})

}

if (wants('CY007')) {

for (const file of coffee) {

findings.push({

rule: 'CY007', name: RULES.CY007[0], level: major !== null && major >= 16 ? 'error' : 'warn',

file: rel(file), line: 1,

message: 'Built-in CoffeeScript support was removed in 16.0. Convert the file to JavaScript or TypeScript.', snippet: '',

})

}

findings.sort((a, b) => a.rule.localeCompare(b.rule) || a.file.localeCompare(b.file) || a.line - b.line)

const summary = {}

for (const f of findings) summary[f.rule] = (summary[f.rule] ?? 0) + 1

if (opts.json) {

process.stdout.write(`${JSON.stringify({

cypress: { range: detected.range, major, source: detected.source },

filesScanned: unique.length,

strict: opts.strict,

summary,

findings,

}, null, 2)}\n`)

} else {

const lines = ['Cypress anti-pattern scan', '']

lines.push(major === null

? 'Cypress version: not detected (pass --cypress-major <n> to grade removed APIs)'

: `Cypress version: major ${major}${detected.range && opts.major === undefined ? ` (range ${detected.range} in ${detected.source})` : ' (from --cypress-major)'}`)

lines.push(`Files scanned: ${unique.length}`)

lines.push(`Findings: ${findings.length}`, '')

if (unique.length === 0) lines.push('No Cypress files found. Pass the folder that contains cypress/ or *.cy.* files.')

for (const rule of Object.keys(summary)) {

const group = findings.filter((f) => f.rule === rule)

lines.push(`${rule} ${RULES[rule][0]} (${group.length})`)

lines.push(` ${RULES[rule][2]}`)

const shown = opts.maxPerRule === 0 ? group : group.slice(0, opts.maxPerRule)

for (const f of shown) {

lines.push(` [${f.level}] ${f.file}:${f.line} ${f.snippet}`)

if (f.message !== RULES[rule][2]) lines.push(` ${f.message}`)

}

if (shown.length < group.length) lines.push(` ... ${group.length - shown.length} more (use --max-per-rule 0 or --json)`)

lines.push('')

}

if (!opts.strict && findings.length > 0) lines.push('Run with --strict to include low-confidence rules (CY1xx).')

process.stdout.write(`${lines.join('\n')}\n`)

}

if (opts.failOn !== 'never') {

const threshold = LEVELS[opts.failOn]

if (findings.some((f) => LEVELS[f.level] >= threshold)) process.exit(1)

}

main()