sounding 0.0.0 → 0.0.2

package/lib/create-world-loader.js

@@ -0,0 +1,128 @@
+const fs = require('node:fs')
+const path = require('node:path')
+const { pathToFileURL } = require('node:url')
+
+const {
+  defineFactory,
+  defineScenario,
+  isFactoryDefinition,
+  isScenarioDefinition,
+} = require('./define-world')
+
+const WORLD_EXTENSIONS = new Set(['.js', '.cjs', '.mjs'])
+
+function listDefinitionFiles(directory) {
+  const output = []
+
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    const nextPath = path.join(directory, entry.name)
+
+    if (entry.isDirectory()) {
+      output.push(...listDefinitionFiles(nextPath))
+      continue
+    }
+
+    if (WORLD_EXTENSIONS.has(path.extname(entry.name))) {
+      output.push(nextPath)
+    }
+  }
+
+  return output.sort()
+}
+
+async function loadModule(filePath) {
+  try {
+    delete require.cache[require.resolve(filePath)]
+    return require(filePath)
+  } catch (error) {
+    if (error.code !== 'ERR_REQUIRE_ESM') {
+      throw error
+    }
+
+    return import(`${pathToFileURL(filePath).href}?t=${Date.now()}`)
+  }
+}
+
+async function registerExport(value, api, source) {
+  const entry = value?.default ?? value
+
+  if (entry === undefined || entry === null) {
+    return
+  }
+
+  if (Array.isArray(entry)) {
+    for (const item of entry) {
+      await registerExport(item, api, source)
+    }
+    return
+  }
+
+  if (isFactoryDefinition(entry) || isScenarioDefinition(entry)) {
+    api.world.register(entry)
+    return
+  }
+
+  if (typeof entry === 'function') {
+    const returned = await entry(api)
+
+    if (returned !== undefined) {
+      await registerExport(returned, api, source)
+    }
+
+    return
+  }
+
+  if (typeof entry === 'object' && (entry.factories || entry.scenarios)) {
+    for (const factory of entry.factories || []) {
+      await registerExport(factory, api, source)
+    }
+
+    for (const scenario of entry.scenarios || []) {
+      await registerExport(scenario, api, source)
+    }
+
+    return
+  }
+
+  throw new Error(
+    `Sounding could not understand the world definition exported from ${source}.`
+  )
+}
+
+async function loadWorldFiles({ world, appPath, config, sails }) {
+  const directories = [config.world?.factories, config.world?.scenarios]
+    .filter(Boolean)
+    .map((relativePath) => path.resolve(appPath, relativePath))
+
+  const loadedFiles = []
+  const api = {
+    sails,
+    world,
+    defineFactory,
+    defineScenario,
+    factory: defineFactory,
+    scenario: defineScenario,
+    registerFactory: world.defineFactory.bind(world),
+    registerScenario: world.defineScenario.bind(world),
+  }
+
+  for (const directory of directories) {
+    if (!fs.existsSync(directory)) {
+      continue
+    }
+
+    for (const filePath of listDefinitionFiles(directory)) {
+      const loaded = await loadModule(filePath)
+      await registerExport(loaded, api, filePath)
+      loadedFiles.push(filePath)
+    }
+  }
+
+  return loadedFiles
+}
+
+module.exports = {
+  loadWorldFiles,
+  listDefinitionFiles,
+  loadModule,
+}

package/lib/default-config.js

@@ -0,0 +1,76 @@
+const DEFAULT_CONFIG = Object.freeze({
+  enableInProduction: false,
+  app: {
+    path: '.',
+    environment: 'test',
+    quiet: true,
+    liftOptions: {},
+  },
+  world: {
+    factories: 'tests/factories',
+    scenarios: 'tests/scenarios',
+  },
+  datastore: {
+    mode: 'managed',
+    identity: 'default',
+    adapter: 'sails-sqlite',
+    root: '.tmp/db',
+    isolation: 'worker',
+  },
+  browser: {
+    enabled: true,
+    type: 'chromium',
+    projects: ['desktop'],
+    defaultProject: 'desktop',
+    launchOptions: {
+      headless: true,
+    },
+  },
+  mail: {
+    capture: true,
+  },
+  request: {
+    transport: 'virtual',
+  },
+  auth: {
+    defaultActor: 'guest',
+    modelIdentity: null,
+    sessionKey: null,
+    worldCollection: null,
+    password: {
+      loginPath: '/login',
+      pagePath: '/login',
+      pageQuery: {},
+      form: {
+        email: 'email',
+        password: 'password',
+        rememberMe: 'rememberMe',
+        returnUrl: 'returnUrl',
+      },
+      selectors: {},
+    },
+  },
+})
+
+function cloneValue(value) {
+  if (Array.isArray(value)) {
+    return value.map(cloneValue)
+  }
+
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, nested]) => [key, cloneValue(nested)])
+    )
+  }
+
+  return value
+}
+
+function getDefaultConfig() {
+  return cloneValue(DEFAULT_CONFIG)
+}
+
+module.exports = {
+  DEFAULT_CONFIG,
+  getDefaultConfig,
+}

package/lib/define-world.js

@@ -0,0 +1,37 @@
+function defineFactory(name, definition) {
+  const entry = {
+    __soundingType: 'factory',
+    name,
+    definition,
+    traits: [],
+    trait(traitName, patch) {
+      entry.traits.push([traitName, patch])
+      return entry
+    },
+  }
+
+  return entry
+}
+
+function defineScenario(name, definition) {
+  return {
+    __soundingType: 'scenario',
+    name,
+    definition,
+  }
+}
+
+function isFactoryDefinition(value) {
+  return value?.__soundingType === 'factory'
+}
+
+function isScenarioDefinition(value) {
+  return value?.__soundingType === 'scenario'
+}
+
+module.exports = {
+  defineFactory,
+  defineScenario,
+  isFactoryDefinition,
+  isScenarioDefinition,
+}

package/lib/merge-config.js

@@ -0,0 +1,25 @@
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+}
+
+function mergeConfig(base, override) {
+  const output = { ...base }
+
+  for (const [key, value] of Object.entries(override || {})) {
+    if (Array.isArray(value)) {
+      output[key] = [...value]
+      continue
+    }
+
+    if (isPlainObject(value) && isPlainObject(base[key])) {
+      output[key] = mergeConfig(base[key], value)
+      continue
+    }
+
+    output[key] = value
+  }
+
+  return output
+}
+
+module.exports = { mergeConfig }

package/lib/normalize-config.js

@@ -0,0 +1,54 @@
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+}
+
+function normalizeDatastore(datastore) {
+  if (typeof datastore === 'string') {
+    return {
+      mode: datastore,
+    }
+  }
+
+  if (!isPlainObject(datastore)) {
+    return datastore
+  }
+
+  const normalized = { ...datastore }
+  const legacyManaged = isPlainObject(normalized.managed) ? normalized.managed : {}
+
+  if (normalized.adapter == null && legacyManaged.adapter != null) {
+    normalized.adapter = legacyManaged.adapter
+  }
+
+  if (normalized.root == null) {
+    normalized.root = legacyManaged.root ?? legacyManaged.directory
+  }
+
+  if (normalized.isolation == null && legacyManaged.isolation != null) {
+    normalized.isolation = legacyManaged.isolation
+  }
+
+  delete normalized.managed
+  delete normalized.directory
+
+  return normalized
+}
+
+function normalizeUserConfig(config = {}) {
+  if (!isPlainObject(config)) {
+    return {}
+  }
+
+  const normalized = { ...config }
+
+  if ('datastore' in normalized) {
+    normalized.datastore = normalizeDatastore(normalized.datastore)
+  }
+
+  return normalized
+}
+
+module.exports = {
+  normalizeDatastore,
+  normalizeUserConfig,
+}

package/lib/resolve-auth-config.js

@@ -0,0 +1,93 @@
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+}
+
+function normalizeIdentity(value) {
+  if (typeof value !== 'string') {
+    return null
+  }
+
+  const normalized = value.trim().toLowerCase()
+  return normalized || null
+}
+
+function titleCase(value) {
+  if (!value) {
+    return value
+  }
+
+  return `${value[0].toUpperCase()}${value.slice(1)}`
+}
+
+function resolveSoundingConfig({ sails, getConfig } = {}) {
+  return (typeof getConfig === 'function' ? getConfig() : null) || sails?.config?.sounding || {}
+}
+
+function getModelByIdentity(sails, identity) {
+  const normalizedIdentity = normalizeIdentity(identity)
+
+  if (!normalizedIdentity) {
+    return null
+  }
+
+  return sails?.models?.[normalizedIdentity] || sails?.models?.[titleCase(normalizedIdentity)] || null
+}
+
+function detectModelIdentity(sails) {
+  for (const candidate of ['user', 'creator']) {
+    if (getModelByIdentity(sails, candidate)) {
+      return candidate
+    }
+  }
+
+  return 'user'
+}
+
+function resolvePasswordConfig(authConfig = {}) {
+  const passwordConfig = isPlainObject(authConfig.password) ? authConfig.password : {}
+  const formConfig = isPlainObject(passwordConfig.form) ? passwordConfig.form : {}
+  const selectorConfig = isPlainObject(passwordConfig.selectors) ? passwordConfig.selectors : {}
+  const form = {
+    email: formConfig.email || 'email',
+    password: formConfig.password || 'password',
+    rememberMe: formConfig.rememberMe || 'rememberMe',
+    returnUrl: formConfig.returnUrl || 'returnUrl',
+  }
+
+  return {
+    loginPath: passwordConfig.loginPath || authConfig.loginPath || '/login',
+    pagePath: passwordConfig.pagePath || passwordConfig.loginPath || authConfig.loginPath || '/login',
+    pageQuery: isPlainObject(passwordConfig.pageQuery) ? passwordConfig.pageQuery : {},
+    form,
+    selectors: {
+      email: selectorConfig.email || `input[name="${form.email}"], input[type="email"]`,
+      password:
+        selectorConfig.password || `input[name="${form.password}"], input[type="password"]`,
+      rememberMe:
+        selectorConfig.rememberMe ||
+        `input[name="${form.rememberMe}"], input[id="${form.rememberMe}"], input[type="checkbox"]`,
+      submit: selectorConfig.submit || 'button[type="submit"], input[type="submit"]',
+    },
+  }
+}
+
+function resolveAuthConfig({ sails, getConfig } = {}) {
+  const soundingConfig = resolveSoundingConfig({ sails, getConfig })
+  const authConfig = isPlainObject(soundingConfig.auth) ? soundingConfig.auth : {}
+  const modelIdentity = normalizeIdentity(authConfig.modelIdentity) || detectModelIdentity(sails)
+
+  return {
+    modelIdentity,
+    model: getModelByIdentity(sails, modelIdentity),
+    sessionKey: authConfig.sessionKey || `${modelIdentity}Id`,
+    worldCollection: authConfig.worldCollection || `${modelIdentity}s`,
+    password: resolvePasswordConfig(authConfig),
+  }
+}
+
+module.exports = {
+  detectModelIdentity,
+  getModelByIdentity,
+  resolveAuthConfig,
+  resolveSoundingConfig,
+}

package/lib/resolve-datastore.js

@@ -0,0 +1,97 @@
+const path = require('node:path')
+
+function getWorkerToken(env = process.env) {
+  return (
+    env.SOUNDING_WORKER_INDEX ||
+    env.PLAYWRIGHT_WORKER_INDEX ||
+    env.TEST_WORKER_INDEX ||
+    String(process.pid)
+  )
+}
+
+function buildManagedSqlitePath({
+  root = path.join(process.cwd(), '.tmp', 'db'),
+  identity = 'default',
+  isolation = 'worker',
+  env = process.env,
+}) {
+  const workerToken = isolation === 'run' ? 'run' : `worker-${getWorkerToken(env)}`
+  return path.join(root, identity, `${workerToken}.db`)
+}
+
+function resolveManagedRoot({ sails, datastore = {}, appPath } = {}) {
+  const configuredRoot = datastore.root || path.join('.tmp', 'db')
+
+  if (path.isAbsolute(configuredRoot)) {
+    return configuredRoot
+  }
+
+  return path.resolve(appPath || sails?.config?.appPath || process.cwd(), configuredRoot)
+}
+
+function resolveDatastore({ sails, soundingConfig }) {
+  const datastoreConfig = soundingConfig.datastore || {}
+  const mode = datastoreConfig.mode || 'managed'
+  const identity = datastoreConfig.identity || 'default'
+  const datastores = (sails.config.datastores ||= {})
+
+  if (mode === 'inherit' || mode === 'external') {
+    const configuredDatastore = datastores[identity]
+
+    if (!configuredDatastore) {
+      throw new Error(
+        `Sounding could not find datastore \`${identity}\` in sails.config.datastores for mode \`${mode}\`.`
+      )
+    }
+
+    return {
+      mode,
+      identity,
+      config: { ...configuredDatastore },
+      managed: false,
+    }
+  }
+
+  if (mode === 'managed') {
+    const adapter = datastoreConfig.adapter || 'sails-sqlite'
+
+    if (adapter !== 'sails-sqlite') {
+      throw new Error(
+        `Sounding only supports managed adapter \`sails-sqlite\` in v0.0.1. Received \`${adapter}\`.`
+      )
+    }
+
+    const filePath = buildManagedSqlitePath({
+      root: resolveManagedRoot({
+        sails,
+        datastore: datastoreConfig,
+      }),
+      identity,
+      isolation: datastoreConfig.isolation || 'worker',
+    })
+
+    const nextDatastore = {
+      ...(datastores[identity] || {}),
+      adapter,
+      url: filePath,
+    }
+
+    datastores[identity] = nextDatastore
+
+    return {
+      mode,
+      identity,
+      config: { ...nextDatastore },
+      managed: true,
+      filePath,
+    }
+  }
+
+  throw new Error(`Unknown Sounding datastore mode: ${mode}`)
+}
+
+module.exports = {
+  buildManagedSqlitePath,
+  resolveManagedRoot,
+  resolveDatastore,
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sounding",
-  "version": "0.0.0",
+  "version": "0.0.2",
   "description": "Testing framework for Sails applications and The Boring JavaScript Stack.",
   "main": "index.js",
   "license": "MIT",
@@ -13,10 +13,26 @@
   ],
   "files": [
     "index.js",
+    "lib",
     "README.md",
     "RESEARCH.md",
     "LICENSE"
   ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "sails": {
+    "isHook": true,
+    "hookName": "sounding"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sailscastshq/sounding.git"
+  },
+  "homepage": "https://github.com/sailscastshq/sounding#readme",
+  "bugs": {
+    "url": "https://github.com/sailscastshq/sounding/issues"
+  },
   "publishConfig": {
     "access": "public"
   }