sounding 0.0.0 → 0.0.2

package/index.js

@@ -1,4 +1,75 @@
-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 isProductionEnvironment(sails) {
+  return (sails.config?.environment || process.env.NODE_ENV) === 'production'
 }
+
+function shouldEnableHook(sails) {
+  return sails.config?.sounding?.enableInProduction === true || !isProductionEnvironment(sails)
+}
+
+function soundingHook(sails) {
+  const runtime = createRuntime(sails)
+
+  return {
+    defaults: {
+      sounding: getDefaultConfig(),
+    },
+
+    configure() {
+      if (!shouldEnableHook(sails)) {
+        return
+      }
+
+      sails.hooks ||= {}
+      sails.sounding = runtime
+      sails.hooks.sounding = this
+      runtime.configure()
+    },
+
+    initialize(done) {
+      if (!shouldEnableHook(sails)) {
+        return 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,279 @@
+const { resolveAuthConfig } = require('./resolve-auth-config')
+
+function normalizeEmail(value) {
+  return String(value || '')
+    .trim()
+    .toLowerCase()
+}
+
+function looksLikeEmail(value) {
+  return typeof value === 'string' && value.includes('@')
+}
+
+function createAuthHelpers({ sails, world, mailbox, request }) {
+  function getAuthConfig() {
+    return resolveAuthConfig({ sails })
+  }
+
+  function getAuthModel() {
+    return getAuthConfig().model
+  }
+
+  function resolveWorldActor(alias) {
+    if (!alias || typeof alias !== 'string') {
+      return null
+    }
+
+    const auth = getAuthConfig()
+
+    return (
+      world.current?.[auth.worldCollection]?.[alias] ||
+      world.current?.users?.[alias] ||
+      world.current?.creators?.[alias] ||
+      null
+    )
+  }
+
+  async function createUserFromEmail(email, fullName) {
+    const auth = getAuthConfig()
+    const User = getAuthModel()
+
+    if (auth.modelIdentity !== 'user') {
+      throw new Error(
+        `Sounding auth helpers could not auto-create a missing ${auth.modelIdentity} record.`
+      )
+    }
+
+    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 resolveActor(actorOrEmail, options = {}) {
+    const auth = getAuthConfig()
+    const User = getAuthModel()
+
+    if (!actorOrEmail) {
+      throw new Error('Sounding auth helpers require an actor or email address.')
+    }
+
+    let candidate = actorOrEmail
+
+    if (typeof candidate === 'string' && !looksLikeEmail(candidate)) {
+      candidate = resolveWorldActor(candidate) || 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 ${auth.modelIdentity} for ${normalizedEmail}.`
+      )
+    }
+
+    return user
+  }
+
+  async function issueMagicLink(actorOrEmail, options = {}) {
+    const User = getAuthModel()
+
+    if (!User?.updateOne) {
+      throw new Error('Sounding auth helpers require an auth model with updateOne().')
+    }
+
+    const user = await resolveActor(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 resolveActor(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,
+    }
+  }
+
+  async function loginWithPassword(actorOrEmail, page, options = {}) {
+    if (!page || typeof page.goto !== 'function') {
+      throw new Error('Sounding password browser login requires a Playwright page.')
+    }
+
+    const auth = getAuthConfig()
+    const actor = await resolveActor(actorOrEmail, {
+      createIfMissing: false,
+      ...options,
+    })
+    const email = normalizeEmail(actor?.email || actorOrEmail)
+
+    if (!options.password) {
+      throw new Error('Sounding password login requires a `password` option.')
+    }
+
+    const loginUrl = new URL(auth.password.pagePath, 'http://sounding.local')
+
+    for (const [key, value] of Object.entries(auth.password.pageQuery || {})) {
+      if (value != null) {
+        loginUrl.searchParams.set(key, String(value))
+      }
+    }
+
+    if (options.returnUrl) {
+      loginUrl.searchParams.set(auth.password.form.returnUrl, options.returnUrl)
+    }
+
+    await page.goto(`${loginUrl.pathname}${loginUrl.search}`)
+    await page.fill(auth.password.selectors.email, email)
+    await page.fill(auth.password.selectors.password, options.password)
+
+    if (options.rememberMe && typeof page.check === 'function') {
+      await page.check(auth.password.selectors.rememberMe)
+    }
+
+    await page.click(auth.password.selectors.submit)
+
+    return {
+      actor,
+      email,
+      path: `${loginUrl.pathname}${loginUrl.search}`,
+    }
+  }
+
+  async function requestWithPassword(actorOrEmail, options = {}) {
+    const auth = getAuthConfig()
+    const actor = await resolveActor(actorOrEmail, {
+      createIfMissing: false,
+      ...options,
+    })
+    const email = normalizeEmail(actor?.email || actorOrEmail)
+
+    if (!options.password) {
+      throw new Error('Sounding password request auth requires a `password` option.')
+    }
+
+    const payload = {
+      [auth.password.form.email]: email,
+      [auth.password.form.password]: options.password,
+    }
+
+    if (options.rememberMe !== undefined) {
+      payload[auth.password.form.rememberMe] = options.rememberMe
+    }
+
+    if (options.returnUrl !== undefined) {
+      payload[auth.password.form.returnUrl] = options.returnUrl
+    }
+
+    const targetRequest = options.request || request
+    const response = await targetRequest.post(
+      auth.password.loginPath,
+      payload,
+      options.requestOptions || {}
+    )
+
+    return {
+      actor,
+      email,
+      request: targetRequest,
+      response,
+    }
+  }
+
+  const login = {
+    async as(actorOrEmail, page, options = {}) {
+      const magicLink = await issueMagicLink(actorOrEmail, options)
+      await page.goto(magicLink.url)
+      return magicLink
+    },
+    withPassword: loginWithPassword,
+  }
+
+  return {
+    conventions: getAuthConfig(),
+    resolveActor,
+    resolveUser: resolveActor,
+    issueMagicLink,
+    requestMagicLink,
+    request: {
+      withPassword: requestWithPassword,
+    },
+    login,
+  }
+}
+
+module.exports = {
+  createAuthHelpers,
+}