@rvoh/psychic-spec-helpers 0.2.0

package/src/feature/matchers/toHavePath.ts

@@ -0,0 +1,23 @@
+import { Page } from 'puppeteer'
+import evaluateWithRetryAndTimeout from '../internal/evaluateWithRetryAndTimeout.js'
+import requirePuppeteerPage from '../internal/requirePuppeteerPage.js'
+
+export default async function toHavePath(page: Page, expectedPath: string) {
+  requirePuppeteerPage(page)
+
+  return await evaluateWithRetryAndTimeout(
+    page,
+    async () => {
+      const pathname = new URL(page.url()).pathname
+
+      return {
+        pass: pathname === expectedPath,
+        actual: expectedPath,
+      }
+    },
+    {
+      successText: () => `Expected page to have path: "${expectedPath}"`,
+      failureText: () => `Expected page not to have path: "${expectedPath}"`,
+    }
+  )
+}

package/src/feature/matchers/toHaveSelector.ts

@@ -0,0 +1,21 @@
+import { Page } from 'puppeteer'
+import evaluateWithRetryAndTimeout from '../internal/evaluateWithRetryAndTimeout.js'
+import requirePuppeteerPage from '../internal/requirePuppeteerPage.js'
+
+export default async function toHaveSelector(page: Page, expectedSelector: string) {
+  return await evaluateWithRetryAndTimeout(
+    page,
+    async () => {
+      requirePuppeteerPage(page)
+
+      return {
+        pass: !!(await page.$(expectedSelector)),
+        actual: expectedSelector,
+      }
+    },
+    {
+      successText: r => `Expected ${r} to have selector: ${expectedSelector}`,
+      failureText: r => `Expected ${r} not to have selector: ${expectedSelector}`,
+    }
+  )
+}

package/src/feature/matchers/toHaveUnchecked.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 toHaveUnchecked(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 unchecked checkbox with text: "${expectedText}"`,
+      failureText: r => `Expected page not to have unchecked checkbox with text: "${expectedText}"`,
+    }
+  )
+}

package/src/feature/matchers/toHaveUrl.ts

@@ -0,0 +1,21 @@
+import { Page } from 'puppeteer'
+import evaluateWithRetryAndTimeout from '../internal/evaluateWithRetryAndTimeout.js'
+import requirePuppeteerPage from '../internal/requirePuppeteerPage.js'
+
+export default async function toHaveUrl(page: Page, expectedUrl: string) {
+  requirePuppeteerPage(page)
+
+  return await evaluateWithRetryAndTimeout(
+    page,
+    async () => {
+      return {
+        pass: page.url() === expectedUrl,
+        actual: expectedUrl,
+      }
+    },
+    {
+      successText: () => `Expected page to have path: "${expectedUrl}"`,
+      failureText: () => `Expected page not to have path: "${expectedUrl}"`,
+    }
+  )
+}

package/src/feature/matchers/toMatchTextContent.ts

@@ -0,0 +1,23 @@
+import { Page } from 'puppeteer'
+import evaluateWithRetryAndTimeout from '../internal/evaluateWithRetryAndTimeout.js'
+import getAllTextContentFromPage from '../internal/getAllTextContentFromPage.js'
+import requirePuppeteerPage from '../internal/requirePuppeteerPage.js'
+
+export default async function toMatchTextContent(argumentPassedToExpect: Page, expected: string) {
+  return await evaluateWithRetryAndTimeout(
+    argumentPassedToExpect,
+    async () => {
+      requirePuppeteerPage(argumentPassedToExpect)
+
+      const actual = await getAllTextContentFromPage(argumentPassedToExpect)
+      return {
+        pass: actual.includes(expected),
+        actual,
+      }
+    },
+    {
+      successText: r => `Expected ${r} to match text ${expected}`,
+      failureText: r => `Expected ${r} not to match text ${expected}`,
+    }
+  )
+}

package/src/feature/matchers/toNotHaveSelector.ts

@@ -0,0 +1,21 @@
+import { Page } from 'puppeteer'
+import evaluateWithRetryAndTimeout from '../internal/evaluateWithRetryAndTimeout.js'
+import requirePuppeteerPage from '../internal/requirePuppeteerPage.js'
+
+export default async function toNotHaveSelector(page: Page, expectedSelector: string) {
+  return await evaluateWithRetryAndTimeout(
+    page,
+    async () => {
+      requirePuppeteerPage(page)
+
+      return {
+        pass: !(await page.$(expectedSelector)),
+        actual: expectedSelector,
+      }
+    },
+    {
+      successText: r => `Expected ${r} not to have selector: ${expectedSelector}`,
+      failureText: r => `Expected ${r} to have selector: ${expectedSelector}`,
+    }
+  )
+}

package/src/feature/matchers/toNotMatchTextContent.ts

@@ -0,0 +1,26 @@
+import { Page } from 'puppeteer'
+import evaluateWithRetryAndTimeout from '../internal/evaluateWithRetryAndTimeout.js'
+import getAllTextContentFromPage from '../internal/getAllTextContentFromPage.js'
+import requirePuppeteerPage from '../internal/requirePuppeteerPage.js'
+
+export default async function toNotMatchTextContent(
+  argumentPassedToExpect: Page,
+  expected: string
+) {
+  return await evaluateWithRetryAndTimeout(
+    argumentPassedToExpect,
+    async () => {
+      requirePuppeteerPage(argumentPassedToExpect)
+
+      const actual = await getAllTextContentFromPage(argumentPassedToExpect)
+      return {
+        pass: !actual.includes(expected),
+        actual,
+      }
+    },
+    {
+      successText: r => `Expected ${r} not to match text ${expected}`,
+      failureText: r => `Expected ${r} to match text ${expected}`,
+    }
+  )
+}

package/src/feature/matchers/toUncheck.ts

@@ -0,0 +1,35 @@
+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 toUncheck(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 unchecked`
+        )
+
+      await checkbox.click()
+      const isCheckedNow = await page.evaluate(checkbox => checkbox.checked, checkbox)
+
+      return {
+        pass: !isCheckedNow,
+        actual: expectedText,
+      }
+    },
+    {
+      successText: r => `Expected page to have uncheckable checkbox with text: "${expectedText}"`,
+      failureText: r =>
+        `Expected page not to have uncheckable checkbox with text: "${expectedText}"`,
+    }
+  )
+}

package/src/index.ts

@@ -0,0 +1,56 @@
+import { ExpectToEvaluateOpts } from './feature/internal/evaluateWithRetryAndTimeout.js'
+import { CustomMatcherResult } from './feature/helpers/providePuppeteerViteMatchers.js'
+
+// unit spec helpers
+export { default as specRequest } from './unit/SpecRequest.js'
+export { default as createPsychicServer } from './unit/createPsychicServer.js'
+export { SpecRequest } from './unit/SpecRequest.js'
+export { SpecSession } from './unit/SpecSession.js'
+
+// feature spec helpers
+export { default as providePuppeteerViteMatchers } from './feature/helpers/providePuppeteerViteMatchers.js'
+export { default as launchBrowser } from './feature/helpers/launchBrowser.js'
+export { default as launchPage } from './feature/helpers/launchPage.js'
+export { default as launchViteServer, stopViteServer } from './feature/helpers/launchViteServer.js'
+export { default as visit } from './feature/helpers/visit.js'
+
+declare global {
+  function context(description: string, callback: () => void): void
+}
+
+declare module 'vitest' {
+  interface ExpectStatic extends PuppeteerAssertions {}
+  interface Assertion extends PuppeteerAssertions {}
+}
+
+interface PuppeteerAssertions {
+  // begin: dream matchers
+  toMatchDreamModel(expected: any): CustomMatcherResult
+  toMatchDreamModels(expected: any): CustomMatcherResult
+  toBeWithin(precision: number, expected: number): CustomMatcherResult
+  toEqualCalendarDate(expected: any): CustomMatcherResult
+
+  // begin: fspec matchers
+  toMatchTextContent(expected: any): Promise<CustomMatcherResult>
+  toNotMatchTextContent(expected: any): Promise<CustomMatcherResult>
+  toHaveSelector(expected: any): Promise<CustomMatcherResult>
+  toNotHaveSelector(expected: any): Promise<CustomMatcherResult>
+  toCheck(expected: any): Promise<CustomMatcherResult>
+  toClick(expected: any): Promise<CustomMatcherResult>
+  toClickLink(expected: any): Promise<CustomMatcherResult>
+  toClickLink(expected: any): Promise<CustomMatcherResult>
+  toClickSelector(expected: any): Promise<CustomMatcherResult>
+  toHavePath(expected: any): Promise<CustomMatcherResult>
+  toHaveUrl(expected: any): Promise<CustomMatcherResult>
+  toHaveChecked(expected: any): Promise<CustomMatcherResult>
+  toHaveUnchecked(expected: any): Promise<CustomMatcherResult>
+  toHaveLink(expected: any): Promise<CustomMatcherResult>
+  toFill(cssSelector: string, text: string): Promise<CustomMatcherResult>
+  toUncheck(expected: any): Promise<CustomMatcherResult>
+  toEvaluate(
+    expected: (a: any) => boolean | Promise<boolean>,
+    opts: ExpectToEvaluateOpts
+  ): Promise<CustomMatcherResult>
+}
+
+export default {}

package/src/shared/sleep.ts

@@ -0,0 +1,7 @@
+export default async function sleep(ms: number) {
+  return await new Promise(accept => {
+    setTimeout(() => {
+      accept(undefined)
+    }, ms)
+  })
+}

package/src/unit/SpecRequest.ts

@@ -0,0 +1,160 @@
+import supertest, { Response } from 'supertest'
+import { createPsychicServer } from '../index.js'
+import supersession, { HttpMethod } from './supersession.js'
+import { SpecSession } from './SpecSession.js'
+
+export class SpecRequest {
+  private PsychicServer: any
+  private server: any
+
+  public async get(
+    uri: string,
+    expectedStatus: number,
+    opts: SpecRequestOptsGet = {}
+  ): Promise<Response> {
+    return await this.makeRequest('get', uri, expectedStatus, opts as SpecRequestOptsAll)
+  }
+
+  public async post(
+    uri: string,
+    expectedStatus: number,
+    opts: SpecRequestOptsPost = {}
+  ): Promise<Response> {
+    return await this.makeRequest('post', uri, expectedStatus, opts as SpecRequestOptsAll)
+  }
+
+  public async put(
+    uri: string,
+    expectedStatus: number,
+    opts: SpecRequestOptsPost = {}
+  ): Promise<Response> {
+    return await this.makeRequest('put', uri, expectedStatus, opts as SpecRequestOptsAll)
+  }
+
+  public async patch(
+    uri: string,
+    expectedStatus: number,
+    opts: SpecRequestOptsPost = {}
+  ): Promise<Response> {
+    return await this.makeRequest('patch', uri, expectedStatus, opts as SpecRequestOptsAll)
+  }
+
+  public async delete(
+    uri: string,
+    expectedStatus: number,
+    opts: SpecRequestOptsPost = {}
+  ): Promise<Response> {
+    return await this.makeRequest('delete', uri, expectedStatus, opts as SpecRequestOptsAll)
+  }
+
+  public async init(PsychicServer: any) {
+    this.PsychicServer = PsychicServer
+    this.server ||= await createPsychicServer(PsychicServer)
+  }
+
+  public async session(
+    uri: string,
+    credentials: object,
+    expectedStatus: number,
+    opts: SpecRequestSessionOpts = {}
+  ): Promise<SpecSession> {
+    return await new Promise((accept, reject) => {
+      createPsychicServer(this.PsychicServer)
+        .then(server => {
+          const session = supersession(server)
+
+          // supersession is borrowed from a non-typescript repo, which
+          // does not have strong types around http methods, so we need to any cast
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-explicit-any
+          ;(session[(opts.httpMethod || 'post') as keyof typeof session] as any)(uri)
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+            .send(credentials)
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+            .expect(expectedStatus)
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+            .query(opts.query || {})
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+            .set(opts.headers || {})
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+            .end((err: Error) => {
+              if (err) return reject(err)
+
+              return accept(new SpecSession(session))
+            })
+        })
+        .catch(err => {
+          throw err
+        })
+    })
+  }
+
+  private async makeRequest(
+    method: 'get' | 'post' | 'put' | 'patch' | 'delete',
+    uri: string,
+    expectedStatus: number,
+    opts: SpecRequestOptsAll = {}
+  ) {
+    // TODO: find out why this is necessary. Currently, without initializing the server
+    // at the beginning of the specs, supertest is unable to use our server to handle requests.
+    // it gives the appearance of being an issue with a runaway promise (i.e. missing await)
+    // but I can't find it anywhere, so I am putting this init method in as a temporary fix.
+    if (!this.server)
+      throw new Error(
+        `
+  ERROR:
+    When making use of the send spec helper, you must first call "await specRequest.init(PsychicServer)"
+    from a beforEach hook at the root of your specs.
+`
+      )
+
+    if (expectedStatus === 500) {
+      process.env.PSYCHIC_EXPECTING_INTERNAL_SERVER_ERROR = '1'
+    }
+
+    const req = supertest.agent(this.server.expressApp)
+    let request = req[method](uri)
+    if (opts.headers) request = request.set(opts.headers)
+    if (opts.query) request = request.query(opts.query)
+    if (method !== 'get') request = request.send(opts.data)
+
+    try {
+      const res = await request.expect(expectedStatus)
+      process.env.PSYCHIC_EXPECTING_INTERNAL_SERVER_ERROR = undefined
+      return res
+    } catch (err) {
+      // without manually console logging, you get no stack trace here
+      console.error(err)
+      console.trace()
+
+      process.env.PSYCHIC_EXPECTING_INTERNAL_SERVER_ERROR = undefined
+
+      throw err
+    }
+  }
+}
+
+export interface SpecRequestOptsAll extends SpecRequestOpts {
+  query?: Record<string, unknown>
+  data?: Record<string, unknown>
+}
+
+export interface SpecRequestOptsGet extends SpecRequestOpts {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  query?: any
+}
+
+export interface SpecRequestOptsPost extends SpecRequestOpts {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  data?: any
+}
+
+export interface SpecRequestOpts {
+  headers?: Record<string, string>
+  allowMocks?: boolean
+}
+
+export interface SpecRequestSessionOpts extends SpecRequestOptsAll {
+  httpMethod?: HttpMethod
+}
+
+export default new SpecRequest()

package/src/unit/SpecSession.ts

@@ -0,0 +1,103 @@
+import { Response } from 'supertest'
+import supersession, { HttpMethod } from './supersession.js'
+
+// like SpecRequest, but meant to be bound to an instance
+// of supersession, enabling chained requests to collect cookies
+export class SpecSession {
+  constructor(private _session: ReturnType<typeof supersession>) {}
+
+  public async get(
+    uri: string,
+    expectedStatus: number,
+    opts: SpecRequestOptsGet = {}
+  ): Promise<Response> {
+    return await this.makeRequest('get', uri, expectedStatus, opts as SpecRequestOptsAll)
+  }
+
+  public async post(
+    uri: string,
+    expectedStatus: number,
+    opts: SpecRequestOptsPost = {}
+  ): Promise<Response> {
+    return await this.makeRequest('post', uri, expectedStatus, opts as SpecRequestOptsAll)
+  }
+
+  public async put(
+    uri: string,
+    expectedStatus: number,
+    opts: SpecRequestOptsPost = {}
+  ): Promise<Response> {
+    return await this.makeRequest('put', uri, expectedStatus, opts as SpecRequestOptsAll)
+  }
+
+  public async patch(
+    uri: string,
+    expectedStatus: number,
+    opts: SpecRequestOptsPost = {}
+  ): Promise<Response> {
+    return await this.makeRequest('patch', uri, expectedStatus, opts as SpecRequestOptsAll)
+  }
+
+  public async delete(
+    uri: string,
+    expectedStatus: number,
+    opts: SpecRequestOptsPost = {}
+  ): Promise<Response> {
+    return await this.makeRequest('delete', uri, expectedStatus, opts as SpecRequestOptsAll)
+  }
+
+  private async makeRequest(
+    method: 'get' | 'post' | 'put' | 'patch' | 'delete',
+    uri: string,
+    expectedStatus: number,
+    opts: SpecRequestOptsAll = {}
+  ) {
+    if (expectedStatus === 500) {
+      process.env.PSYCHIC_EXPECTING_INTERNAL_SERVER_ERROR = '1'
+    }
+
+    const req = this._session
+    let request = req[method](uri)
+    if (opts.headers) request = request.set(opts.headers)
+    if (opts.query) request = request.query(opts.query)
+    if (method !== 'get') request = request.send(opts.data)
+
+    try {
+      const res = await request.expect(expectedStatus)
+      process.env.PSYCHIC_EXPECTING_INTERNAL_SERVER_ERROR = undefined
+      return res
+    } catch (err) {
+      // without manually console logging, you get no stack trace here
+      console.error(err)
+      console.trace()
+
+      process.env.PSYCHIC_EXPECTING_INTERNAL_SERVER_ERROR = undefined
+
+      throw err
+    }
+  }
+}
+
+export interface SpecRequestOptsAll extends SpecRequestOpts {
+  query?: Record<string, unknown>
+  data?: Record<string, unknown>
+}
+
+export interface SpecRequestOptsGet extends SpecRequestOpts {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  query?: any
+}
+
+export interface SpecRequestOptsPost extends SpecRequestOpts {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  data?: any
+}
+
+export interface SpecRequestOpts {
+  headers?: Record<string, string>
+  allowMocks?: boolean
+}
+
+export interface SpecRequestSessionOpts extends SpecRequestOptsAll {
+  httpMethod?: HttpMethod
+}

package/src/unit/createPsychicServer.ts

@@ -0,0 +1,8 @@
+const _server: any = undefined
+export default async function createPsychicServer(PsychicServer: any) {
+  if (_server) return _server!
+
+  const server = new PsychicServer()
+  await server.boot()
+  return server
+}

package/src/unit/supersession.ts

@@ -0,0 +1,100 @@
+import { CookieAccessInfo as CookieAccess } from 'cookiejar'
+import http from 'http'
+import request from 'supertest'
+import URL, { UrlWithStringQuery } from 'url'
+
+// NOTE: this is not original code.
+// it was adapted from a non-typescript library with an uncertain future:
+//
+// https://github.com/rjz/supertest-session/blob/master/index.js
+
+type AgentOptions = Parameters<typeof request.agent>[1]
+
+class Supersession {
+  private app: http.Server
+  private agent: ReturnType<typeof request.agent>
+  private url: UrlWithStringQuery
+  private cookieAccess: CookieAccess
+
+  constructor(
+    server: any,
+    private options: AgentOptions = {}
+  ) {
+    if (!server.expressApp) {
+      throw new Error('Supersession requires an `app`')
+    }
+
+    this.agent = request.agent(server.expressApp, options)
+
+    const app = http.createServer(server.expressApp)
+    const url = (request as any).Test.prototype.serverAddress(app, '/')
+
+    this.app = app
+    this.url = URL.parse(url)
+
+    this.reset()
+
+    // typescript is telling me I don't need to worry about options.helpers,
+    // but leaving this commented out in case we need to revisit
+    // if (this.options.helpers instanceof Object) {
+    //   assign(this, this.options.helpers)
+    // }
+  }
+
+  get cookies() {
+    return (this.agent as any).jar.getCookies(this.cookieAccess)
+  }
+
+  public reset() {
+    // Unset supertest-session options before forwarding options to superagent.
+    var agentOptions = {
+      ...this.options,
+      before: undefined,
+      cookieAccess: undefined,
+      destroy: undefined,
+      helpers: undefined,
+    }
+
+    this.agent = request.agent(this.app, agentOptions)
+
+    const domain = this.url.hostname
+    const path = this.url.path
+    const secure = 'https:' == this.url.protocol
+    const script = false
+    this.cookieAccess = (CookieAccess as any)(domain, path, secure, script)
+  }
+
+  destroy() {
+    if ((this.options as any).destroy) (this.options as any).destroy.call(this)
+    this.reset()
+  }
+
+  request(method: HttpMethod, route: string) {
+    var test = this.agent[method](route)
+
+    // typescript is telling me I don't need to worry about options.before,
+    // but leaving this commented out in case we need to revisit
+    // if (this.options.before) {
+    //   this.options.before.call(this, test)
+    // }
+
+    return test
+  }
+}
+
+export const HttpMethods = ['get', 'post', 'put', 'patch', 'delete', 'options'] as const
+export type HttpMethod = (typeof HttpMethods)[number]
+
+HttpMethods.forEach(function (m) {
+  ;(Supersession as any).prototype[m as any] = function () {
+    var args = [].slice.call(arguments)
+    return this.request.apply(this, [m].concat(args))
+  }
+})
+
+export default function supersession(
+  server: any,
+  config: AgentOptions = {}
+): ReturnType<typeof request> {
+  return new Supersession(server, config) as unknown as ReturnType<typeof request>
+}

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "./tsconfig.esm.build.json",
+  "include": ["src/**/*"],
+  "compilerOptions": {
+    "types": ["vitest/globals"]
+  }
+}