sounding 0.0.0 → 0.0.1

package/lib/create-test-api.js

@@ -0,0 +1,228 @@
+const nodeTest = require('node:test')
+const { createAppManager } = require('./create-app-manager')
+const { createExpect } = require('./create-expect')
+
+let defaultAppManager = null
+let defaultCleanupRegistered = false
+let trialQueue = Promise.resolve()
+
+function getDefaultAppManager() {
+  defaultAppManager ||= createAppManager()
+  return defaultAppManager
+}
+
+function ensureDefaultAppManagerCleanup() {
+  if (defaultCleanupRegistered || typeof nodeTest.after !== 'function') {
+    return
+  }
+
+  nodeTest.after(async () => {
+    if (defaultAppManager) {
+      await defaultAppManager.lower()
+    }
+  })
+
+  defaultCleanupRegistered = true
+}
+
+function normalizeTestArgs(title, optionsOrHandler, maybeHandler) {
+  if (typeof optionsOrHandler === 'function') {
+    return {
+      title,
+      options: {},
+      handler: optionsOrHandler,
+    }
+  }
+
+  return {
+    title,
+    options: optionsOrHandler || {},
+    handler: maybeHandler,
+  }
+}
+
+async function resolveRuntimeFromGlobals(options = {}) {
+  const runtime = globalThis.sounding || globalThis.sails?.sounding || globalThis.sails?.hooks?.sounding
+  const requiresHttp = Boolean(options.http || options.browser)
+  const httpServer = globalThis.sails?.hooks?.http?.server
+  const hasHttpServer = Boolean(
+    httpServer &&
+      (httpServer.listening ||
+        (typeof httpServer.address === 'function' && httpServer.address()))
+  )
+
+  if (runtime && (!requiresHttp || hasHttpServer)) {
+    return {
+      sounding: runtime,
+      teardown: async () => runtime.lower(),
+    }
+  }
+
+  const appManager = getDefaultAppManager()
+  ensureDefaultAppManagerCleanup()
+  const sounding = await appManager.runtime({ http: requiresHttp })
+  return {
+    sounding,
+    teardown: async () => sounding.lower(),
+  }
+}
+
+function bindRequestMethod(request, method) {
+  return typeof request?.[method] === 'function' ? request[method].bind(request) : undefined
+}
+
+function splitTestOptions(options = {}) {
+  const {
+    transport,
+    browser,
+    ...nodeOptions
+  } = options
+
+  return {
+    nodeOptions: {
+      concurrency: false,
+      ...nodeOptions,
+    },
+    trialOptions: {
+      transport,
+      browser,
+    },
+  }
+}
+
+async function runInTrialQueue(handler) {
+  const previous = trialQueue
+  let release = () => {}
+
+  trialQueue = new Promise((resolve) => {
+    release = resolve
+  })
+
+  await previous
+
+  try {
+    return await handler()
+  } finally {
+    release()
+  }
+}
+
+async function runTrial({ runtime, mode, nodeContext, handler, options = {} }) {
+  const activeRuntime = typeof runtime === 'function' ? await runtime() : runtime
+  const resolved = activeRuntime
+    ? {
+        sounding: activeRuntime,
+        teardown: async () => activeRuntime.lower(),
+      }
+    : await resolveRuntimeFromGlobals({
+        http: options.transport === 'http',
+        browser: Boolean(options.browser),
+      })
+  const sounding = resolved.sounding
+  const booted = await sounding.boot({ mode })
+  const sails = booted.sails || {}
+
+  sails.sounding ||= sounding
+  sails.hooks ||= {}
+  sails.hooks.sounding ||= sounding
+  sails.helpers ||= sounding.helpers
+
+  const request = options.transport ? sounding.request.using(options.transport) : sounding.request
+  const visit = options.transport ? sounding.visit.using(options.transport) : sounding.visit
+
+  let browserSession = null
+  if (options.browser) {
+    browserSession = await sounding.browser.open(options.browser === true ? {} : options.browser)
+  }
+
+  const expect = browserSession?.expect
+    ? createExpect.withFallback(browserSession.expect)
+    : createExpect
+
+  const context = {
+    ...nodeContext,
+    t: nodeContext,
+    expect,
+    sails,
+    request,
+    visit,
+    auth: sounding.auth,
+    login: sounding.auth?.login,
+    world: sounding.world,
+    mailbox: sounding.mailbox,
+    browser: browserSession?.browser,
+    browserContext: browserSession?.context,
+    page: browserSession?.page,
+    get: bindRequestMethod(request, 'get'),
+    head: bindRequestMethod(request, 'head'),
+    post: bindRequestMethod(request, 'post'),
+    put: bindRequestMethod(request, 'put'),
+    patch: bindRequestMethod(request, 'patch'),
+    del: bindRequestMethod(request, 'delete'),
+  }
+
+  try {
+    return await handler(context)
+  } finally {
+    await resolved.teardown()
+  }
+}
+
+function createTrialMethod(baseTest, runtime, mode) {
+  return function registerTrial(title, optionsOrHandler, maybeHandler) {
+    const { options, handler } = normalizeTestArgs(title, optionsOrHandler, maybeHandler)
+    const { nodeOptions, trialOptions } = splitTestOptions(options)
+
+    return baseTest(title, nodeOptions, async (nodeContext) => {
+      return runInTrialQueue(async () => {
+        return runTrial({
+          runtime,
+          mode,
+          nodeContext,
+          handler,
+          options: trialOptions,
+        })
+      })
+    })
+  }
+}
+
+function createTestApi({ baseTest = nodeTest, runtime } = {}) {
+  function soundingTest(title, optionsOrHandler, maybeHandler) {
+    const { options, handler } = normalizeTestArgs(title, optionsOrHandler, maybeHandler)
+    const { nodeOptions, trialOptions } = splitTestOptions(options)
+
+    return baseTest(title, nodeOptions, async (nodeContext) => {
+      return runInTrialQueue(async () => {
+        return runTrial({
+          runtime,
+          mode: 'trial',
+          nodeContext,
+          handler,
+          options: trialOptions,
+        })
+      })
+    })
+  }
+
+  soundingTest.skip = (...args) => baseTest.skip(...args)
+  soundingTest.todo = (...args) => baseTest.todo(...args)
+  if (typeof baseTest.only === 'function') {
+    soundingTest.only = (...args) => baseTest.only(...args)
+  }
+
+  // Temporary compatibility aliases while the public docs move fully to `test()`.
+  soundingTest.helper = createTrialMethod(baseTest, runtime, 'helper')
+  soundingTest.endpoint = createTrialMethod(baseTest, runtime, 'endpoint')
+
+  return soundingTest
+}
+
+module.exports = {
+  createTestApi,
+  normalizeTestArgs,
+  resolveRuntimeFromGlobals,
+  runInTrialQueue,
+  runTrial,
+  splitTestOptions,
+}

package/lib/create-visit-client.js

@@ -0,0 +1,114 @@
+const DEFAULT_HEADERS = {
+  'x-inertia': 'true',
+  'x-requested-with': 'XMLHttpRequest',
+  accept: 'text/html, application/xhtml+xml',
+}
+
+function joinHeaderValue(value) {
+  return Array.isArray(value) ? value.join(',') : value
+}
+
+function buildVisitHeaders(options = {}) {
+  const headers = {
+    ...(options.headers || {}),
+  }
+
+  if (options.version) {
+    headers['x-inertia-version'] = options.version
+  }
+
+  if (options.errorBag) {
+    headers['x-inertia-error-bag'] = options.errorBag
+  }
+
+  if (options.only?.length) {
+    if (!options.component) {
+      throw new Error('Sounding visit() requires `component` when using `only`.')
+    }
+
+    headers['x-inertia-partial-component'] = options.component
+    headers['x-inertia-partial-data'] = joinHeaderValue(options.only)
+  }
+
+  if (options.except?.length) {
+    if (!options.component) {
+      throw new Error('Sounding visit() requires `component` when using `except`.')
+    }
+
+    headers['x-inertia-partial-component'] = options.component
+    headers['x-inertia-partial-except'] = joinHeaderValue(options.except)
+  }
+
+  if (options.reset?.length) {
+    headers['x-inertia-reset'] = joinHeaderValue(options.reset)
+  }
+
+  return headers
+}
+
+function buildRequestOptions(options = {}) {
+  const {
+    component,
+    only,
+    except,
+    reset,
+    errorBag,
+    version,
+    ...requestOptions
+  } = options
+
+  const visitHeaders = buildVisitHeaders({
+    component,
+    only,
+    except,
+    reset,
+    errorBag,
+    version,
+    headers: requestOptions.headers,
+  })
+
+  const output = {
+    ...requestOptions,
+  }
+
+  if (Object.keys(visitHeaders).length > 0) {
+    output.headers = visitHeaders
+  }
+
+  return output
+}
+
+function createVisitClient({ request }) {
+  const client = request.withHeaders(DEFAULT_HEADERS)
+
+  function visit(target, options = {}) {
+    return client.get(target, buildRequestOptions(options))
+  }
+
+  visit.get = (target, options = {}) => client.get(target, buildRequestOptions(options))
+  visit.head = (target, options = {}) => client.head(target, buildRequestOptions(options))
+  visit.post = (target, payload, options = {}) => client.post(target, payload, buildRequestOptions(options))
+  visit.put = (target, payload, options = {}) => client.put(target, payload, buildRequestOptions(options))
+  visit.patch = (target, payload, options = {}) =>
+    client.patch(target, payload, buildRequestOptions(options))
+  visit.delete = (target, payload, options = {}) =>
+    client.delete(target, payload, buildRequestOptions(options))
+  visit.del = visit.delete
+  visit.using = (transport) => createVisitClient({ request: request.using(transport) })
+
+  Object.defineProperty(visit, 'transport', {
+    enumerable: true,
+    get() {
+      return client.transport
+    },
+  })
+
+  return visit
+}
+
+module.exports = {
+  createVisitClient,
+  DEFAULT_HEADERS,
+  buildVisitHeaders,
+  buildRequestOptions,
+}

package/lib/create-world-engine.js

@@ -0,0 +1,300 @@
+const {
+  isFactoryDefinition,
+  isScenarioDefinition,
+} = require('./define-world')
+
+function mergeValue(base, patch) {
+  if (typeof patch === 'function') {
+    return patch(base)
+  }
+
+  return {
+    ...base,
+    ...(patch || {}),
+  }
+}
+
+function createFakeHelpers({ sequence }) {
+  return {
+    person: {
+      fullName() {
+        return `Test User ${sequence('fake-person')}`
+      },
+    },
+    internet: {
+      email() {
+        return `user${sequence('fake-email')}@example.com`
+      },
+    },
+    lorem: {
+      words(count = 3) {
+        return Array.from({ length: count }, () => `word-${sequence('fake-word')}`).join(' ')
+      },
+      sentence(count = 6) {
+        return `${Array.from({ length: count }, () => `word-${sequence('fake-sentence')}`).join(' ')}.`
+      },
+    },
+  }
+}
+
+function createThenableBuilder(executor, initialOverrides = {}) {
+  const state = {
+    overrides: initialOverrides,
+    traits: [],
+  }
+
+  function run() {
+    return executor(state.overrides, {
+      traits: [...state.traits],
+    })
+  }
+
+  const builder = {
+    trait(name) {
+      state.traits.push(name)
+      return builder
+    },
+
+    traits(names = []) {
+      state.traits.push(...names)
+      return builder
+    },
+
+    with(overrides = {}) {
+      state.overrides = overrides
+      return builder
+    },
+
+    value() {
+      return run()
+    },
+
+    then(onFulfilled, onRejected) {
+      return Promise.resolve(run()).then(onFulfilled, onRejected)
+    },
+
+    catch(onRejected) {
+      return Promise.resolve(run()).catch(onRejected)
+    },
+
+    finally(onFinally) {
+      return Promise.resolve(run()).finally(onFinally)
+    },
+  }
+
+  return builder
+}
+
+function createWorldEngine({ sails }) {
+  const factories = new Map()
+  const scenarios = new Map()
+  const sequences = new Map()
+  let currentWorld = null
+  let currentSeed = null
+
+  function sequence(nameOrBuilder = 'default', maybeBuilder) {
+    const name = typeof nameOrBuilder === 'function' ? 'default' : nameOrBuilder
+    const builder = typeof nameOrBuilder === 'function' ? nameOrBuilder : maybeBuilder
+    const next = (sequences.get(name) || 0) + 1
+    sequences.set(name, next)
+    return typeof builder === 'function' ? builder(next) : next
+  }
+
+  function resolveFactory(name) {
+    const entry = factories.get(name)
+
+    if (!entry) {
+      throw new Error(`Unknown Sounding factory: ${name}`)
+    }
+
+    return entry
+  }
+
+  function buildOne(name, overrides = {}, options = {}) {
+    const entry = resolveFactory(name)
+    const helpers = {
+      fake: createFakeHelpers({ sequence }),
+      sequence,
+      seed: currentSeed,
+      sails,
+    }
+
+    let value =
+      typeof entry.definition === 'function'
+        ? entry.definition(helpers)
+        : { ...entry.definition }
+
+    for (const traitName of options.traits || []) {
+      if (!entry.traits.has(traitName)) {
+        throw new Error(`Unknown Sounding trait \`${traitName}\` for factory \`${name}\``)
+      }
+
+      value = mergeValue(value, entry.traits.get(traitName))
+    }
+
+    return {
+      ...value,
+      ...overrides,
+    }
+  }
+
+  async function createOne(name, overrides = {}, options = {}) {
+    const value = buildOne(name, overrides, options)
+    const model = sails?.models?.[name]
+
+    if (model?.create) {
+      const query = model.create(value)
+      return typeof query.fetch === 'function' ? query.fetch() : query
+    }
+
+    return value
+  }
+
+  function registerFactoryDefinition(entry) {
+    const nextEntry = {
+      definition: entry.definition,
+      traits: new Map(entry.traits || []),
+    }
+
+    factories.set(entry.name, nextEntry)
+
+    return {
+      trait(traitName, patch) {
+        nextEntry.traits.set(traitName, patch)
+        return this
+      },
+    }
+  }
+
+  function registerScenarioDefinition(entry) {
+    scenarios.set(entry.name, entry.definition)
+    return entry
+  }
+
+  function defineFactory(nameOrEntry, definition) {
+    if (isFactoryDefinition(nameOrEntry)) {
+      return registerFactoryDefinition(nameOrEntry)
+    }
+
+    const entry = {
+      name: nameOrEntry,
+      definition,
+      traits: [],
+    }
+
+    return registerFactoryDefinition(entry)
+  }
+
+  function defineScenario(nameOrEntry, definition) {
+    if (isScenarioDefinition(nameOrEntry)) {
+      return registerScenarioDefinition(nameOrEntry)
+    }
+
+    return registerScenarioDefinition({
+      name: nameOrEntry,
+      definition,
+    })
+  }
+
+  async function use(name, context = {}) {
+    const definition = scenarios.get(name)
+
+    if (!definition) {
+      throw new Error(`Unknown Sounding scenario: ${name}`)
+    }
+
+    currentWorld = await definition({
+      build(name, overrides = {}) {
+        return createThenableBuilder(
+          (nextOverrides, options) => buildOne(name, nextOverrides, options),
+          overrides
+        )
+      },
+      create(name, overrides = {}) {
+        return createThenableBuilder(
+          (nextOverrides, options) => createOne(name, nextOverrides, options),
+          overrides
+        )
+      },
+      defineFactory,
+      defineScenario,
+      sails,
+      sequence,
+      seed: currentSeed,
+      context,
+    })
+
+    return currentWorld
+  }
+
+  return {
+    build(name, overrides = {}, options = {}) {
+      return buildOne(name, overrides, options)
+    },
+
+    async buildMany(name, count, overrides = {}, options = {}) {
+      return Array.from({ length: count }, () => buildOne(name, overrides, options))
+    },
+
+    create(name, overrides = {}, options = {}) {
+      return createOne(name, overrides, options)
+    },
+
+    async createMany(name, count, overrides = {}, options = {}) {
+      const records = []
+      for (let index = 0; index < count; index += 1) {
+        records.push(await createOne(name, overrides, options))
+      }
+      return records
+    },
+
+    defineFactory,
+    defineScenario,
+
+    register(definition) {
+      if (isFactoryDefinition(definition)) {
+        return defineFactory(definition)
+      }
+
+      if (isScenarioDefinition(definition)) {
+        return defineScenario(definition)
+      }
+
+      throw new Error('Sounding could not register an unknown world definition.')
+    },
+
+    get current() {
+      return currentWorld
+    },
+
+    get factories() {
+      return Array.from(factories.keys())
+    },
+
+    get scenarios() {
+      return Array.from(scenarios.keys())
+    },
+
+    reset(options = {}) {
+      const { preserveSequences = false } = options
+
+      factories.clear()
+      scenarios.clear()
+      if (!preserveSequences) {
+        sequences.clear()
+      }
+      currentWorld = null
+      currentSeed = null
+    },
+
+    seed(value) {
+      currentSeed = value
+      return currentSeed
+    },
+
+    sequence,
+    use,
+  }
+}
+
+module.exports = { createWorldEngine }