sounding 0.0.0 → 0.0.1

package/index.js

@@ -1,4 +1,59 @@
-module.exports = {
-  name: 'sounding',
-  version: '0.0.0'
+const { createRuntime } = require('./lib/create-runtime')
+const { createAppManager } = require('./lib/create-app-manager')
+const { createMailbox } = require('./lib/create-mailbox')
+const { createMailCapture } = require('./lib/create-mail-capture')
+const { createWorldEngine } = require('./lib/create-world-engine')
+const { loadWorldFiles } = require('./lib/create-world-loader')
+const { defineFactory, defineScenario } = require('./lib/define-world')
+const { createHelperRunner } = require('./lib/create-helper-runner')
+const { createRequestClient } = require('./lib/create-request-client')
+const { createVisitClient } = require('./lib/create-visit-client')
+const { createBrowserManager } = require('./lib/create-browser-manager')
+const { createAuthHelpers } = require('./lib/create-auth-helpers')
+const { createExpect } = require('./lib/create-expect')
+const { createTestApi } = require('./lib/create-test-api')
+const { getDefaultConfig } = require('./lib/default-config')
+
+function soundingHook(sails) {
+  const runtime = createRuntime(sails)
+
+  return {
+    defaults: {
+      sounding: getDefaultConfig(),
+    },
+
+    configure() {
+      sails.hooks ||= {}
+      sails.sounding = runtime
+      sails.hooks.sounding = this
+      runtime.configure()
+    },
+
+    initialize(done) {
+      sails.sounding = runtime
+      Object.assign(this, runtime)
+      sails.hooks.sounding = this
+      return done()
+    },
+  }
 }
+
+module.exports = soundingHook
+module.exports.test = createTestApi()
+module.exports.expect = createExpect
+module.exports.defineFactory = defineFactory
+module.exports.defineScenario = defineScenario
+module.exports.createRuntime = createRuntime
+module.exports.createAppManager = createAppManager
+module.exports.createMailbox = createMailbox
+module.exports.createWorldEngine = createWorldEngine
+module.exports.loadWorldFiles = loadWorldFiles
+module.exports.createHelperRunner = createHelperRunner
+module.exports.createRequestClient = createRequestClient
+module.exports.createVisitClient = createVisitClient
+module.exports.createBrowserManager = createBrowserManager
+module.exports.createAuthHelpers = createAuthHelpers
+module.exports.createExpect = createExpect
+module.exports.createTestApi = createTestApi
+module.exports.getDefaultConfig = getDefaultConfig
+module.exports.createMailCapture = createMailCapture

package/lib/create-app-manager.js

@@ -0,0 +1,329 @@
+const fs = require('node:fs')
+const path = require('node:path')
+
+const { getDefaultConfig } = require('./default-config')
+const { mergeConfig } = require('./merge-config')
+const { normalizeUserConfig } = require('./normalize-config')
+const { buildManagedSqlitePath, resolveManagedRoot } = require('./resolve-datastore')
+
+function resolveModuleFromApp(appPath, moduleId) {
+  return require(require.resolve(moduleId, { paths: [appPath, process.cwd(), __dirname] }))
+}
+
+function loadAppSoundingConfig(appPath) {
+  const configPath = path.join(appPath, 'config', 'sounding.js')
+
+  if (!fs.existsSync(configPath)) {
+    return getDefaultConfig()
+  }
+
+  delete require.cache[require.resolve(configPath)]
+  const loaded = require(configPath)
+  return mergeConfig(getDefaultConfig(), normalizeUserConfig(loaded?.sounding || {}))
+}
+
+function buildManagedDatastoreOverrides(config, appPath) {
+  if (config.datastore?.mode !== 'managed') {
+    return {}
+  }
+
+  const identity = config.datastore.identity || 'default'
+
+  return {
+    datastores: {
+      [identity]: {
+        adapter: config.datastore.adapter || 'sails-sqlite',
+        url: buildManagedSqlitePath({
+          root: resolveManagedRoot({
+            datastore: config.datastore,
+            appPath,
+          }),
+          identity,
+          isolation: config.datastore.isolation || 'worker',
+        }),
+      },
+    },
+    models: {
+      migrate: 'drop',
+    },
+  }
+}
+
+function createOutputFilter(config = {}) {
+  if (config.app?.quiet === false) {
+    return {
+      install() {},
+      uninstall() {},
+    }
+  }
+
+  const noisyPatterns = [
+    /start\s+build started/i,
+    /ready\s+built in/i,
+    /\[DEP0044\].*util\.isArray/i,
+    /node --trace-deprecation/i,
+    /^\s*info:\s/m,
+    /success:\s*true.*no new issues to notify/i,
+  ]
+
+  let installed = false
+  let originalStdoutWrite = null
+  let originalStderrWrite = null
+
+  function shouldSuppress(chunk) {
+    const value = String(chunk || '')
+    const normalizedValue = value.replace(/\u001b\[[0-9;]*m/g, '')
+    return noisyPatterns.some((pattern) => pattern.test(normalizedValue))
+  }
+
+  function wrapWrite(write) {
+    return function soundingWrite(chunk, encoding, callback) {
+      if (shouldSuppress(chunk)) {
+        if (typeof encoding === 'function') {
+          encoding()
+        }
+
+        if (typeof callback === 'function') {
+          callback()
+        }
+
+        return true
+      }
+
+      return write.call(this, chunk, encoding, callback)
+    }
+  }
+
+  return {
+    install() {
+      if (installed) {
+        return
+      }
+
+      originalStdoutWrite = process.stdout.write
+      originalStderrWrite = process.stderr.write
+      process.stdout.write = wrapWrite(originalStdoutWrite)
+      process.stderr.write = wrapWrite(originalStderrWrite)
+      installed = true
+    },
+
+    uninstall() {
+      if (!installed) {
+        return
+      }
+
+      process.stdout.write = originalStdoutWrite
+      process.stderr.write = originalStderrWrite
+      originalStdoutWrite = null
+      originalStderrWrite = null
+      installed = false
+    },
+  }
+}
+
+function resolveManagedDatastoreFile(config, appPath) {
+  if (config.datastore?.mode !== 'managed') {
+    return null
+  }
+
+  const identity = config.datastore.identity || 'default'
+
+  return buildManagedSqlitePath({
+    root: resolveManagedRoot({
+      datastore: config.datastore,
+      appPath,
+    }),
+    identity,
+    isolation: config.datastore.isolation || 'worker',
+  })
+}
+
+function createAppManager({
+  appPath = process.cwd(),
+  environment = 'test',
+  liftOptions = {},
+  SailsConstructor,
+} = {}) {
+  let loadedApp = null
+  let liftedApp = null
+  let loadPromise = null
+  let liftPromise = null
+  const managedArtifacts = new Set()
+  let outputFilter = null
+
+  function resolveAppPath() {
+    return path.resolve(appPath)
+  }
+
+  function resolveConfig() {
+    return loadAppSoundingConfig(resolveAppPath())
+  }
+
+  function resolveSailsConstructor() {
+    if (SailsConstructor) {
+      return SailsConstructor
+    }
+
+    return resolveModuleFromApp(resolveAppPath(), 'sails').constructor
+  }
+
+  function buildOptions(mode) {
+    const config = resolveConfig()
+    outputFilter ||= createOutputFilter(config)
+    const managedFile = resolveManagedDatastoreFile(config, resolveAppPath())
+
+    if (managedFile) {
+      managedArtifacts.add(managedFile)
+    }
+
+    const appConfig = config.app || {}
+    const baseOptions = {
+      appPath: resolveAppPath(),
+      environment: appConfig.environment || environment,
+      ...buildManagedDatastoreOverrides(config, resolveAppPath()),
+    }
+    const modeOptions =
+      mode === 'load'
+        ? mergeConfig(
+            {
+              hooks: {
+                shipwright: false,
+                content: false,
+              },
+            },
+            appConfig.loadOptions || {}
+          )
+        : mergeConfig(appConfig.liftOptions || {}, liftOptions)
+    const nextOptions = mergeConfig(baseOptions, modeOptions)
+
+    if (mode === 'load' && nextOptions.datastores?.content) {
+      delete nextOptions.datastores.content
+    }
+
+    return nextOptions
+  }
+
+  async function cleanupManagedArtifacts() {
+    for (const filePath of managedArtifacts) {
+      const companionPaths = [
+        filePath,
+        `${filePath}-journal`,
+        `${filePath}-wal`,
+        `${filePath}-shm`,
+      ]
+
+      for (const artifactPath of companionPaths) {
+        await fs.promises.rm(artifactPath, { force: true }).catch(() => {})
+      }
+    }
+  }
+
+  async function load() {
+    if (loadedApp) {
+      return loadedApp
+    }
+
+    if (loadPromise) {
+      return loadPromise
+    }
+
+    const Sails = resolveSailsConstructor()
+    const sailsApp = new Sails()
+    const nextLoadOptions = buildOptions('load')
+    outputFilter?.install()
+
+    loadPromise = new Promise((resolve, reject) => {
+      sailsApp.load(nextLoadOptions, (error, loadedSails) => {
+        if (error) {
+          loadPromise = null
+          cleanupManagedArtifacts().catch(() => {})
+          outputFilter?.uninstall()
+          reject(error)
+          return
+        }
+
+        loadedApp = loadedSails
+        globalThis.sails = loadedSails
+        globalThis.sounding = loadedSails.sounding
+        resolve(loadedSails)
+      })
+    })
+
+    return loadPromise
+  }
+
+  async function lift() {
+    if (liftedApp) {
+      return liftedApp
+    }
+
+    if (liftPromise) {
+      return liftPromise
+    }
+
+    const Sails = resolveSailsConstructor()
+    const sailsApp = new Sails()
+    const nextLiftOptions = buildOptions('lift')
+    outputFilter?.install()
+
+    liftPromise = new Promise((resolve, reject) => {
+      sailsApp.lift(nextLiftOptions, (error, liftedSails) => {
+        if (error) {
+          liftPromise = null
+          cleanupManagedArtifacts().catch(() => {})
+          outputFilter?.uninstall()
+          reject(error)
+          return
+        }
+
+        liftedApp = liftedSails
+        globalThis.sails = liftedSails
+        globalThis.sounding = liftedSails.sounding
+        resolve(liftedSails)
+      })
+    })
+
+    return liftPromise
+  }
+
+  async function runtime(options = {}) {
+    const app = options.http ? await lift() : await load()
+    return app.sounding || app.hooks?.sounding
+  }
+
+  async function lower() {
+    const apps = [loadedApp, liftedApp].filter(Boolean)
+
+    loadedApp = null
+    liftedApp = null
+    loadPromise = null
+    liftPromise = null
+
+    await Promise.all(
+      apps.map(
+        (app) =>
+          new Promise((resolve) => {
+            app.lower(() => resolve())
+          })
+      )
+    )
+
+    delete globalThis.sails
+    delete globalThis.sounding
+    outputFilter?.uninstall()
+    await cleanupManagedArtifacts()
+  }
+
+  return {
+    load,
+    lift,
+    runtime,
+    lower,
+    resolveConfig,
+  }
+}
+
+module.exports = {
+  createAppManager,
+  loadAppSoundingConfig,
+}

package/lib/create-auth-helpers.js

@@ -0,0 +1,159 @@
+function normalizeEmail(value) {
+  return String(value || '')
+    .trim()
+    .toLowerCase()
+}
+
+function looksLikeEmail(value) {
+  return typeof value === 'string' && value.includes('@')
+}
+
+function createAuthHelpers({ sails, world, mailbox, request }) {
+  function getUserModel() {
+    return sails?.models?.user || sails?.models?.User
+  }
+
+  async function createUserFromEmail(email, fullName) {
+    const User = getUserModel()
+
+    if (!sails?.helpers?.user?.signupWithTeam) {
+      throw new Error(
+        'Sounding auth helpers could not find `sails.helpers.user.signupWithTeam`.'
+      )
+    }
+
+    const signupResult = await sails.helpers.user.signupWithTeam.with({
+      fullName: fullName || normalizeEmail(email).split('@')[0],
+      email: normalizeEmail(email),
+      tosAcceptedByIp: '127.0.0.1',
+      emailStatus: 'verified',
+    })
+
+    if (User?.updateOne) {
+      await User.updateOne({ id: signupResult.user.id }).set({
+        emailStatus: 'verified',
+      })
+    }
+
+    if (User?.findOne) {
+      return User.findOne({ id: signupResult.user.id })
+    }
+
+    return signupResult.user
+  }
+
+  async function resolveUser(actorOrEmail, options = {}) {
+    const User = getUserModel()
+
+    if (!actorOrEmail) {
+      throw new Error('Sounding auth helpers require an actor, user, or email address.')
+    }
+
+    let candidate = actorOrEmail
+
+    if (typeof candidate === 'string' && world.current?.users?.[candidate]) {
+      candidate = world.current.users[candidate]
+    }
+
+    if (candidate?.id && User?.findOne) {
+      return User.findOne({ id: candidate.id }) || candidate
+    }
+
+    const email = candidate?.email || (looksLikeEmail(candidate) ? candidate : null)
+
+    if (!email) {
+      throw new Error(
+        `Sounding auth helpers could not resolve an email address for actor \`${candidate}\`.`
+      )
+    }
+
+    const normalizedEmail = normalizeEmail(email)
+    let user = User?.findOne ? await User.findOne({ email: normalizedEmail }) : null
+
+    if (!user && options.createIfMissing !== false) {
+      user = await createUserFromEmail(normalizedEmail, candidate?.fullName || options.fullName)
+    }
+
+    if (!user) {
+      throw new Error(
+        `Sounding auth helpers could not find a user for ${normalizedEmail}.`
+      )
+    }
+
+    return user
+  }
+
+  async function issueMagicLink(actorOrEmail, options = {}) {
+    const User = getUserModel()
+
+    if (!User?.updateOne) {
+      throw new Error('Sounding auth helpers require a User model with updateOne().')
+    }
+
+    const user = await resolveUser(actorOrEmail, {
+      createIfMissing: true,
+      ...options,
+    })
+    const token = await sails.helpers.magicLink.generateToken()
+    const hashedToken = await sails.helpers.magicLink.hashToken(token)
+
+    await User.updateOne({ id: user.id }).set({
+      emailStatus: 'verified',
+      magicLinkToken: hashedToken,
+      magicLinkTokenExpiresAt: Date.now() + 15 * 60 * 1000,
+      magicLinkTokenUsedAt: null,
+    })
+
+    const refreshedUser = User.findOne ? await User.findOne({ id: user.id }) : user
+
+    return {
+      user: refreshedUser,
+      email: refreshedUser.email,
+      token,
+      url: `/magic-link/${token}`,
+    }
+  }
+
+  async function requestMagicLink(actorOrEmail, options = {}) {
+    const user = await resolveUser(actorOrEmail, {
+      createIfMissing: true,
+      ...options,
+    })
+
+    const response = await request.post(
+      '/magic-link',
+      {
+        email: user.email,
+        fullName: options.fullName || user.fullName,
+        redirectUrl: options.redirectUrl || '/login',
+      },
+      options.requestOptions || {}
+    )
+
+    return {
+      response,
+      email: user.email,
+      message: mailbox.latest(),
+      url: mailbox.latest()?.ctaUrl,
+    }
+  }
+
+  const login = {
+    async as(actorOrEmail, page, options = {}) {
+      const magicLink = await issueMagicLink(actorOrEmail, options)
+      await page.goto(magicLink.url)
+      return magicLink
+    },
+  }
+
+  return {
+    resolveUser,
+    issueMagicLink,
+    requestMagicLink,
+    login,
+  }
+}
+
+module.exports = {
+  createAuthHelpers,
+}

package/lib/create-browser-manager.js

@@ -0,0 +1,132 @@
+const { resolveBaseUrl } = require('./create-request-client')
+
+function resolveModuleFromApp(appPath, moduleId) {
+  return require(require.resolve(moduleId, { paths: [appPath, process.cwd(), __dirname] }))
+}
+
+function defaultLoadPlaywright(appPath) {
+  return resolveModuleFromApp(appPath, 'playwright')
+}
+
+function defaultLoadPlaywrightTest(appPath) {
+  return resolveModuleFromApp(appPath, '@playwright/test')
+}
+
+function resolveProjectOptions(projectName, devices = {}) {
+  if (projectName === 'mobile') {
+    return (
+      devices['iPhone 13'] || {
+        viewport: {
+          width: 390,
+          height: 844,
+        },
+        isMobile: true,
+        hasTouch: true,
+      }
+    )
+  }
+
+  return {}
+}
+
+function createBrowserManager({
+  sails,
+  getConfig,
+  appPathResolver = () => sails?.config?.appPath || process.cwd(),
+  loadPlaywright = defaultLoadPlaywright,
+  loadPlaywrightTest = defaultLoadPlaywrightTest,
+} = {}) {
+  let session = null
+
+  async function open(options = {}) {
+    if (session) {
+      return session
+    }
+
+    const config = typeof getConfig === 'function' ? getConfig() : sails?.config?.sounding || {}
+
+    if (config.browser?.enabled === false) {
+      throw new Error('Sounding browser support is disabled in `config/sounding.js`.')
+    }
+
+    const appPath = appPathResolver()
+    const playwright = await loadPlaywright(appPath)
+    const playwrightTest = await Promise.resolve()
+      .then(() => loadPlaywrightTest(appPath))
+      .catch(() => null)
+
+    const browserTypeName = options.type || config.browser?.type || 'chromium'
+    const browserType = playwright?.[browserTypeName]
+
+    if (!browserType?.launch) {
+      throw new Error(
+        `Sounding could not find a Playwright browser type named \`${browserTypeName}\`.`
+      )
+    }
+
+    const projectName =
+      options.project ||
+      config.browser?.defaultProject ||
+      config.browser?.projects?.[0] ||
+      'desktop'
+
+    const browser = await browserType.launch({
+      headless: true,
+      ...(config.browser?.launchOptions || {}),
+      ...(options.launchOptions || {}),
+    })
+
+    const context = await browser.newContext({
+      baseURL: resolveBaseUrl({ sails, getConfig }),
+      ...resolveProjectOptions(projectName, playwright.devices || {}),
+      ...(options.contextOptions || {}),
+    })
+
+    const page = await context.newPage()
+
+    session = {
+      playwright,
+      browser,
+      context,
+      page,
+      expect: playwrightTest?.expect,
+      project: projectName,
+    }
+
+    return session
+  }
+
+  async function close() {
+    if (!session) {
+      return
+    }
+
+    await session.context?.close?.()
+    await session.browser?.close?.()
+    session = null
+  }
+
+  return {
+    open,
+    close,
+    get active() {
+      return Boolean(session?.page)
+    },
+    get page() {
+      return session?.page
+    },
+    get context() {
+      return session?.context
+    },
+    get expect() {
+      return session?.expect
+    },
+  }
+}
+
+module.exports = {
+  createBrowserManager,
+  defaultLoadPlaywright,
+  defaultLoadPlaywrightTest,
+  resolveProjectOptions,
+}