@rvoh/psychic-spec-helpers 0.2.0

package/package.json

@@ -0,0 +1,47 @@
+{
+  "type": "module",
+  "name": "@rvoh/psychic-spec-helpers",
+  "version": "0.2.0",
+  "description": "psychic framework spec helpers",
+  "main": "./dist/cjs/src/index.js",
+  "module": "./dist/esm/src/index.js",
+  "types": "./dist/types/src/index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./dist/cjs/src/index.js",
+      "import": "./dist/esm/src/index.js",
+      "types": "./dist/types/src/index.d.ts"
+    }
+  },
+  "files": [
+    "tsconfig.json",
+    "src/**/*",
+    "dist/**/*"
+  ],
+  "scripts": {
+    "build": "echo \"building psychic-spec-helpers...\" && rm -rf dist && npx tsc -p ./tsconfig.json",
+    "prepack": "yarn build"
+  },
+  "packageManager": "yarn@4.4.1",
+  "peerDependencies": {
+    "@types/node": "*",
+    "@types/supertest": "*",
+    "puppeteer": "*",
+    "supertest": "*",
+    "ts-node": "*",
+    "typescript": "*"
+  },
+  "devDependencies": {
+    "@types/cookiejar": "^2",
+    "@types/node": "^22.5.1",
+    "@types/supertest": "^6.0.2",
+    "puppeteer": "^24.4.0",
+    "supertest": "^7.0.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.5.4",
+    "vitest": "^3.0.8"
+  },
+  "dependencies": {
+    "cookiejar": "^2.1.4"
+  }
+}

package/src/feature/helpers/launchBrowser.ts

@@ -0,0 +1,10 @@
+import puppeteer, { LaunchOptions } from 'puppeteer'
+
+export default async function launchBrowser(opts?: LaunchOptions) {
+  return await puppeteer.launch({
+    browser: 'firefox',
+    dumpio: process.env.DEBUG === '1',
+    headless: true,
+    ...opts,
+  })
+}

package/src/feature/helpers/launchPage.ts

@@ -0,0 +1,7 @@
+import { LaunchOptions } from 'puppeteer'
+import launchBrowser from './launchBrowser.js'
+
+export default async function launchPage(opts?: LaunchOptions) {
+  const browser = await launchBrowser(opts)
+  return browser.newPage()
+}

package/src/feature/helpers/launchViteServer.ts

@@ -0,0 +1,104 @@
+import { ChildProcessWithoutNullStreams, spawn } from 'child_process'
+import { createServer } from 'net'
+import sleep from '../../shared/sleep.js'
+
+let serverProcess: ChildProcessWithoutNullStreams | undefined = undefined
+
+export default async function launchViteServer({
+  port = 3000,
+  cmd = 'yarn client',
+  timeout = 5000,
+}: { port?: number; cmd?: string; timeout?: number } = {}) {
+  if (serverProcess) return
+
+  if (process.env.DEBUG === '1') console.log('Starting server...')
+  const [_cmd, ...args] = cmd.split(' ')
+
+  serverProcess = spawn(_cmd, args, {
+    detached: true,
+    env: {
+      ...process.env,
+      BROWSER: 'none',
+      VITE_PSYCHIC_ENV: 'test',
+    },
+  })
+
+  await waitForPort(port, timeout)
+
+  serverProcess.stdout.on('data', data => {
+    if (process.env.DEBUG === '1') console.log(`Server output: ${data}`)
+  })
+
+  serverProcess.on('error', err => {
+    throw err
+  })
+
+  serverProcess.stdout.on('data', data => {
+    if (process.env.DEBUG === '1') console.log(`Server output: ${data}`)
+  })
+
+  serverProcess.stderr.on('data', data => {
+    if (process.env.DEBUG === '1') console.error(`Server error: ${data}`)
+  })
+
+  serverProcess.on('error', err => {
+    console.error(`Server process error: ${err as unknown as string}`)
+  })
+
+  serverProcess.on('close', code => {
+    if (process.env.DEBUG === '1') console.log(`Server process exited with code ${code}`)
+  })
+}
+
+export function stopViteServer() {
+  if (serverProcess?.pid) {
+    if (process.env.DEBUG === '1') console.log('Stopping server...')
+    // serverProcess.kill('SIGINT')
+    process.kill(-serverProcess.pid, 'SIGKILL')
+    serverProcess = undefined
+
+    if (process.env.DEBUG === '1') console.log('server stopped')
+  }
+}
+
+async function isPortAvailable(port: number): Promise<boolean> {
+  return new Promise(resolve => {
+    const server = createServer()
+      .once('error', err => {
+        if ((err as any).code === 'EADDRINUSE') {
+          resolve(false)
+        } else {
+          resolve(true)
+        }
+      })
+      .once('listening', () => {
+        server.close()
+        resolve(true)
+      })
+      .listen(port, '127.0.0.1')
+  })
+}
+
+async function waitForPort(port: number, timeout: number = 5000) {
+  if (await isPortAvailable(port)) {
+    return true
+  }
+
+  const startTime = Date.now()
+
+  async function recursiveWaitForPort() {
+    if (await isPortAvailable(port)) {
+      return true
+    }
+
+    if (Date.now() > startTime + timeout) {
+      stopViteServer()
+      throw new Error('waited too long for port: ' + port)
+    }
+
+    await sleep(50)
+    return await recursiveWaitForPort()
+  }
+
+  return await recursiveWaitForPort()
+}

package/src/feature/helpers/providePuppeteerViteMatchers.ts

@@ -0,0 +1,102 @@
+import { Page } from 'puppeteer'
+import evaluateWithRetryAndTimeout, {
+  ExpectToEvaluateOpts,
+  ExpectToEvaluateReturnType,
+} from '../internal/evaluateWithRetryAndTimeout.js'
+import toHaveSelector from '../matchers/toHaveSelector.js'
+import toMatchTextContent from '../matchers/toMatchTextContent.js'
+import toNotHaveSelector from '../matchers/toNotHaveSelector.js'
+import toNotMatchTextContent from '../matchers/toNotMatchTextContent.js'
+import toCheck from '../matchers/toCheck.js'
+import toUncheck from '../matchers/toUncheck.js'
+import toClick from '../matchers/toClick.js'
+import toClickLink from '../matchers/toClickLink.js'
+import toClickButton from '../matchers/toClickButton.js'
+import toClickSelector from '../matchers/toClickSelector.js'
+import toHavePath from '../matchers/toHavePath.js'
+import toHaveUrl from '../matchers/toHaveUrl.js'
+import toHaveLink from '../matchers/toHaveLink.js'
+import toHaveChecked from '../matchers/toHaveChecked.js'
+import toHaveUnchecked from '../matchers/toHaveUnchecked.js'
+import toFill from '../matchers/toFill.js'
+
+export default function providePuppeteerViteMatchers() {
+  ;((global as any).expect as any).extend({
+    async toMatchTextContent(page: Page, text: string) {
+      return await toMatchTextContent(page, text)
+    },
+
+    async toNotMatchTextContent(page: Page, text: string) {
+      return await toNotMatchTextContent(page, text)
+    },
+
+    async toHaveSelector(page: Page, cssSelector: string) {
+      return await toHaveSelector(page, cssSelector)
+    },
+
+    async toNotHaveSelector(page: Page, cssSelector: string) {
+      return await toNotHaveSelector(page, cssSelector)
+    },
+
+    async toCheck(page: Page, text: string) {
+      return await toCheck(page, text)
+    },
+
+    async toClick(page: Page, text: string) {
+      return await toClick(page, text)
+    },
+
+    async toClickLink(page: Page, text: string) {
+      return await toClickLink(page, text)
+    },
+
+    async toClickButton(page: Page, text: string) {
+      return await toClickButton(page, text)
+    },
+
+    async toClickSelector(page: Page, cssSelector: string) {
+      return await toClickSelector(page, cssSelector)
+    },
+
+    async toHavePath(page: Page, path: string) {
+      return await toHavePath(page, path)
+    },
+
+    async toHaveUrl(page: Page, url: string) {
+      return await toHaveUrl(page, url)
+    },
+
+    async toHaveChecked(page: Page, text: string) {
+      return await toHaveChecked(page, text)
+    },
+
+    async toHaveUnchecked(page: Page, checked: string) {
+      return await toHaveUnchecked(page, checked)
+    },
+
+    async toHaveLink(page: Page, text: string) {
+      return await toHaveLink(page, text)
+    },
+
+    async toFill(page: Page, cssSelector: string, text: string) {
+      return await toFill(page, cssSelector, text)
+    },
+
+    async toUncheck(page: Page, text: string) {
+      return await toUncheck(page, text)
+    },
+
+    async toEvaluate(
+      argumentPassedToExpect: Page,
+      evaluationFn: (a: any) => ExpectToEvaluateReturnType | Promise<ExpectToEvaluateReturnType>,
+      opts: ExpectToEvaluateOpts
+    ) {
+      return await evaluateWithRetryAndTimeout(argumentPassedToExpect, evaluationFn, opts)
+    },
+  })
+}
+
+export interface CustomMatcherResult {
+  pass: boolean
+  message: (actual?: unknown) => string
+}

package/src/feature/helpers/visit.ts

@@ -0,0 +1,11 @@
+import { Page } from 'puppeteer'
+import launchPage from './launchPage.js'
+
+export default async function visit(
+  path: string,
+  { page, baseUrl = 'http://localhost:3000' }: { page?: Page; baseUrl?: string } = {}
+) {
+  page ||= await launchPage()
+  await page.goto(`${baseUrl}/${path.replace(/^\//, '')}`)
+  return page
+}

package/src/feature/internal/evaluateWithRetryAndTimeout.ts

@@ -0,0 +1,49 @@
+import sleep from '../../shared/sleep.js'
+
+export default async function evaluateWithRetryAndTimeout(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  argumentPassedToExpect: any,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  evaluationFn: (a: any) => ExpectToEvaluateReturnType | Promise<ExpectToEvaluateReturnType>,
+  opts: ExpectToEvaluateOpts
+) {
+  const timeout = opts.timeout || 4000
+  const interval = opts.interval || 10
+  const startTime = Date.now()
+
+  async function intervalCb() {
+    const res = await evaluationFn(argumentPassedToExpect)
+    const expired = Date.now() >= startTime + timeout
+
+    if (res.pass) {
+      return {
+        message: () => (opts.successText ? opts.successText(res.actual) : 'Success'),
+        pass: true,
+      }
+    }
+
+    if (expired) {
+      return {
+        message: () => opts.failureText(res.actual),
+        pass: false,
+      }
+    }
+
+    await sleep(interval)
+    return await intervalCb()
+  }
+
+  return await intervalCb()
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ExpectToEvaluateReturnType = { pass: boolean; actual: any }
+
+export interface ExpectToEvaluateOpts {
+  timeout?: number
+  interval?: number
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  successText?: (received: any) => string
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  failureText: (received: any) => string
+}

package/src/feature/internal/evaluationFailure.ts

@@ -0,0 +1,6 @@
+export default function evaluationFailure(actual: any) {
+  return {
+    pass: false,
+    actual,
+  }
+}

package/src/feature/internal/evaluationSuccess.ts

@@ -0,0 +1,6 @@
+export default function evaluationSuccess(actual: any) {
+  return {
+    pass: true,
+    actual,
+  }
+}

package/src/feature/internal/getAllTextContentFromPage.ts

@@ -0,0 +1,26 @@
+import { Page } from 'puppeteer'
+
+export default async function getAllTextContentFromPage(page: Page) {
+  // Evaluate and extract all text content on the page
+  const allText = await page.evaluate(() => {
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access
+    const elements = document.body.querySelectorAll('*')
+
+    const textContentArray: string[] = []
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ;(elements as any[]).forEach(element => {
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access
+      if (element.textContent.trim() !== '') {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access
+        textContentArray.push(element.innerText.trim())
+      }
+    })
+
+    return textContentArray.join(' ')
+  })
+
+  return allText
+}

package/src/feature/internal/isPuppeteerPage.ts

@@ -0,0 +1,3 @@
+export default function isPuppeteerPage(page: any): boolean {
+  return typeof page === 'object' && page !== null && !!page.mouse
+}

package/src/feature/internal/matchFailure.ts

@@ -0,0 +1,6 @@
+export default function matchFailure(message: string | ((expected: any) => string)) {
+  return {
+    pass: false,
+    message: (expected: any) => (typeof message === 'string' ? message : message(expected)),
+  }
+}

package/src/feature/internal/matchSuccess.ts

@@ -0,0 +1,6 @@
+export default function matchSuccess(message: string | ((expected: any) => string)) {
+  return {
+    pass: true,
+    message: (expected: any) => (typeof message === 'string' ? message : message(expected)),
+  }
+}

package/src/feature/internal/requirePuppeteerPage.ts

@@ -0,0 +1,7 @@
+import isPuppeteerPage from './isPuppeteerPage.js'
+
+export default function requirePuppeteerPage(argumentPassedToExpect: any) {
+  if (!isPuppeteerPage(argumentPassedToExpect)) {
+    throw new Error('Must pass a puppeteer page to expect when calling toMatchTextContent')
+  }
+}

package/src/feature/matchers/toCheck.ts

@@ -0,0 +1,34 @@
+import { Page } from 'puppeteer'
+import evaluateWithRetryAndTimeout from '../internal/evaluateWithRetryAndTimeout.js'
+import evaluationFailure from '../internal/evaluationFailure.js'
+import requirePuppeteerPage from '../internal/requirePuppeteerPage.js'
+
+export default async function toCheck(page: Page, expectedText: string) {
+  return await evaluateWithRetryAndTimeout(
+    page,
+    async () => {
+      requirePuppeteerPage(page)
+
+      const checkbox = await page.$(`input[type="checkbox"][value="${expectedText}"]`)
+      if (!checkbox) return evaluationFailure(`A checkbox was not found with "${expectedText}"`)
+
+      const isChecked = await page.evaluate(checkbox => checkbox.checked, checkbox)
+      if (isChecked)
+        return evaluationFailure(
+          `A checkbox was found with "${expectedText}", but it is already checked`
+        )
+
+      await checkbox.click()
+      const isCheckedNow = await page.evaluate(checkbox => checkbox.checked, checkbox)
+
+      return {
+        pass: isCheckedNow,
+        actual: expectedText,
+      }
+    },
+    {
+      successText: r => `Expected page to have checkable checkbox with text: "${expectedText}"`,
+      failureText: r => `Expected page not to have checkable checkbox with text: "${expectedText}"`,
+    }
+  )
+}

package/src/feature/matchers/toClick.ts

@@ -0,0 +1,30 @@
+import { Page, TimeoutError } from 'puppeteer'
+import evaluateWithRetryAndTimeout from '../internal/evaluateWithRetryAndTimeout.js'
+import evaluationFailure from '../internal/evaluationFailure.js'
+import requirePuppeteerPage from '../internal/requirePuppeteerPage.js'
+
+export default async function toClick(page: Page, expectedText: string) {
+  return await evaluateWithRetryAndTimeout(
+    page,
+    async () => {
+      requirePuppeteerPage(page)
+
+      try {
+        const el = await page.locator(`::-p-text(${expectedText})`).setTimeout(5000).wait()
+        await el.click()
+      } catch (err) {
+        if (err instanceof TimeoutError) return evaluationFailure(expectedText)
+        throw err
+      }
+
+      return {
+        pass: true,
+        actual: expectedText,
+      }
+    },
+    {
+      successText: () => `Expected page to have clickable element with text: "${expectedText}"`,
+      failureText: () => `Expected page not to have clickable element with text: "${expectedText}"`,
+    }
+  )
+}

package/src/feature/matchers/toClickButton.ts

@@ -0,0 +1,30 @@
+import { Page, TimeoutError } from 'puppeteer'
+import evaluateWithRetryAndTimeout from '../internal/evaluateWithRetryAndTimeout.js'
+import evaluationFailure from '../internal/evaluationFailure.js'
+import requirePuppeteerPage from '../internal/requirePuppeteerPage.js'
+
+export default async function toClickButton(page: Page, expectedText: string) {
+  return await evaluateWithRetryAndTimeout(
+    page,
+    async () => {
+      requirePuppeteerPage(page)
+
+      try {
+        const el = await page.locator(`button ::-p-text(${expectedText})`).setTimeout(10).wait()
+        await el.click()
+      } catch (err) {
+        if (err instanceof TimeoutError) return evaluationFailure(expectedText)
+        throw err
+      }
+
+      return {
+        pass: true,
+        actual: expectedText,
+      }
+    },
+    {
+      successText: () => `Expected page to have clickable button with text: "${expectedText}"`,
+      failureText: () => `Expected page not to have clickable button with text: "${expectedText}"`,
+    }
+  )
+}

package/src/feature/matchers/toClickLink.ts

@@ -0,0 +1,30 @@
+import { Page, TimeoutError } from 'puppeteer'
+import evaluateWithRetryAndTimeout from '../internal/evaluateWithRetryAndTimeout.js'
+import evaluationFailure from '../internal/evaluationFailure.js'
+import requirePuppeteerPage from '../internal/requirePuppeteerPage.js'
+
+export default async function toClickLink(page: Page, expectedText: string) {
+  return await evaluateWithRetryAndTimeout(
+    page,
+    async () => {
+      requirePuppeteerPage(page)
+
+      try {
+        const el = await page.locator(`a ::-p-text(${expectedText})`).setTimeout(5000).wait()
+        await el.click()
+      } catch (err) {
+        if (err instanceof TimeoutError) return evaluationFailure(expectedText)
+        throw err
+      }
+
+      return {
+        pass: true,
+        actual: expectedText,
+      }
+    },
+    {
+      successText: () => `Expected page to have clickable link with text: "${expectedText}"`,
+      failureText: () => `Expected page not to have clickable link with text: "${expectedText}"`,
+    }
+  )
+}

package/src/feature/matchers/toClickSelector.ts

@@ -0,0 +1,30 @@
+import { Page, TimeoutError } from 'puppeteer'
+import evaluateWithRetryAndTimeout from '../internal/evaluateWithRetryAndTimeout.js'
+import evaluationFailure from '../internal/evaluationFailure.js'
+import requirePuppeteerPage from '../internal/requirePuppeteerPage.js'
+
+export default async function toClickSelector(page: Page, cssSelector: string) {
+  return await evaluateWithRetryAndTimeout(
+    page,
+    async () => {
+      requirePuppeteerPage(page)
+
+      try {
+        const el = await page.locator(cssSelector).setTimeout(10).wait()
+        await el.click()
+      } catch (err) {
+        if (err instanceof TimeoutError) return evaluationFailure(cssSelector)
+        throw err
+      }
+
+      return {
+        pass: true,
+        actual: cssSelector,
+      }
+    },
+    {
+      successText: () => `Expected page to have clickable selector with text: "${cssSelector}"`,
+      failureText: () => `Expected page not to have clickable selector with text: "${cssSelector}"`,
+    }
+  )
+}

package/src/feature/matchers/toFill.ts

@@ -0,0 +1,28 @@
+import { Page } from 'puppeteer'
+import evaluateWithRetryAndTimeout from '../internal/evaluateWithRetryAndTimeout.js'
+import evaluationFailure from '../internal/evaluationFailure.js'
+import requirePuppeteerPage from '../internal/requirePuppeteerPage.js'
+
+export default async function toFill(page: Page, cssSelector: string, text: string) {
+  return await evaluateWithRetryAndTimeout(
+    page,
+    async () => {
+      requirePuppeteerPage(page)
+
+      try {
+        await page.type(cssSelector, text)
+      } catch {
+        return evaluationFailure(text)
+      }
+
+      return {
+        pass: true,
+        actual: text,
+      }
+    },
+    {
+      successText: () => `Expected page to have clickable link with text: "${text}"`,
+      failureText: () => `Expected page not to have clickable link with text: "${text}"`,
+    }
+  )
+}

package/src/feature/matchers/toHaveChecked.ts

@@ -0,0 +1,26 @@
+import { Page } from 'puppeteer'
+import evaluateWithRetryAndTimeout from '../internal/evaluateWithRetryAndTimeout.js'
+import evaluationFailure from '../internal/evaluationFailure.js'
+import requirePuppeteerPage from '../internal/requirePuppeteerPage.js'
+
+export default async function toHaveChecked(page: Page, expectedText: string) {
+  return await evaluateWithRetryAndTimeout(
+    page,
+    async () => {
+      requirePuppeteerPage(page)
+
+      const checkbox = await page.$(`input[type="checkbox"][value="${expectedText}"]`)
+      if (!checkbox) return evaluationFailure(`A checkbox was not found with "${expectedText}"`)
+
+      const isChecked = await page.evaluate(checkbox => checkbox.checked, checkbox)
+      return {
+        pass: isChecked,
+        actual: expectedText,
+      }
+    },
+    {
+      successText: r => `Expected page to have checked checkbox with text: "${expectedText}"`,
+      failureText: r => `Expected page not to have checked checkbox with text: "${expectedText}"`,
+    }
+  )
+}

package/src/feature/matchers/toHaveLink.ts

@@ -0,0 +1,30 @@
+import { Page, TimeoutError } from 'puppeteer'
+import evaluateWithRetryAndTimeout from '../internal/evaluateWithRetryAndTimeout.js'
+import evaluationFailure from '../internal/evaluationFailure.js'
+import requirePuppeteerPage from '../internal/requirePuppeteerPage.js'
+
+export default async function toHaveLink(page: Page, expectedText: string) {
+  return await evaluateWithRetryAndTimeout(
+    page,
+    async () => {
+      requirePuppeteerPage(page)
+
+      let el: any = undefined
+      try {
+        el = await page.locator(`a ::-p-text(${expectedText})`).setTimeout(10).wait()
+      } catch (err) {
+        if (err instanceof TimeoutError) return evaluationFailure(expectedText)
+        throw err
+      }
+
+      return {
+        pass: !!el,
+        actual: expectedText,
+      }
+    },
+    {
+      successText: () => `Expected page to have clickable link with text: "${expectedText}"`,
+      failureText: () => `Expected page not to have clickable link with text: "${expectedText}"`,
+    }
+  )
+}