sounding 0.0.3 → 0.1.0

package/README.md

@@ -16,17 +16,63 @@ The canonical Sails-native surface is:
 - `get('/api/issues')` or `sails.sounding.request.get('/api/issues')` inside endpoint-style trials
 - `await auth.login.withPassword('creator@example.com', page, { password: 'secret123' })` inside browser trials
 - `await auth.request.withPassword('creator@example.com', { password: 'secret123' })` inside request trials
+- `test('...', { world: 'signed-in-user' }, async ({ request }) => {})` can auto-load named worlds before the handler runs
+- `request.as('owner')` and `visit.as('owner')` can resolve actor aliases from the current world
+- `test('...', { browser: 'mobile' }, async ({ page }) => {})` can select a named browser project without extra ceremony
+- failed browser trials capture the current URL and a full-page screenshot under `.tmp/sounding/artifacts`
 - request helpers default to Sails virtual requests powered by `sails.request()`
+- virtual request responses expose the final `req.session` snapshot as `response.session`; HTTP responses leave it undefined
+- request assertions can check auth/session state with `expect(response).toHaveSession('userId', user.id)` and flash messages with `expect(response).toHaveFlash('info', /welcome/i)`
+- failed response assertions include concise request/response diagnostics; set `SOUNDING_DIAGNOSTICS=verbose` for full response excerpts
 - Inertia-style visits can use `visit('/pricing')` and partial reload options like `{ component, only }`
+- mail assertions can check captured emails with `expect(mailbox).toHaveSentMail({ to, subject })` and `expect(mailbox.latest()).toHaveCtaUrl(/magic-link/)`
 - a trial can opt into stricter parity with `test('...', { transport: 'http' }, ...)`
+- upload trials use `FormData` over the HTTP transport so Sails can exercise real Skipper streams
+- independent trials can opt into concurrent execution with `test('...', { concurrent: true }, ...)` or `test.concurrent(...)`
 - any trial can also scope a request client with `sails.sounding.request.using('http')`
 
 Sounding also owns its own built-in world engine, so the same package can:
 - define factories under `tests/factories`
 - define scenarios under `tests/scenarios`
-- load named worlds for endpoint and browser trials
+- auto-load named worlds for endpoint, Inertia, socket, and browser trials
+- compose world records with fluent builders like `await create('user').trait('admin').with({ email })`
+- merge repeated builder `.with()` calls, with `.withOnly()` available when you want to use only the next overrides
 - capture outgoing mail by wrapping `sails.helpers.mail.send` and storing normalized messages in `sails.sounding.mailbox`
 
+Request-level Inertia trials can assert page contracts without launching a browser:
+
+```js
+const { test } = require('sounding')
+
+test('dashboard shows the signed-in creator', { world: 'signed-in-user' }, async ({ visit, expect }) => {
+  const page = await visit.as('owner')('/dashboard')
+
+  expect(page).toBeInertiaPage('dashboard/index')
+  expect(page).toHaveInertiaProps({
+    'auth.user.email': 'owner@example.com',
+    'stats.projects': 2,
+    projects: [{ name: 'Launch Plan' }],
+  })
+  expect(page).toHaveNoInertiaErrors()
+})
+
+test('dashboard partial reload returns only notifications', async ({ visit, expect }) => {
+  const page = await visit('/dashboard', {
+    component: 'dashboard/index',
+    only: ['notifications'],
+    reset: ['sidebar'],
+  })
+
+  expect(page).toBeInertiaPage('dashboard/index')
+  expect(page).toHaveInertiaPartialReload({
+    component: 'dashboard/index',
+    only: ['notifications'],
+    reset: ['sidebar'],
+  })
+  expect(page).toHaveOnlyInertiaProps(['notifications'])
+})
+```
+
 The default configuration story is intentionally calm:
 - Sounding only enables its hook in the environments listed under `sounding.environments`
 - the default is `['test']`, so non-test boot paths stay dark unless you opt in explicitly
@@ -36,6 +82,10 @@ The default configuration story is intentionally calm:
 - managed SQLite artifacts live under `.tmp/db`
 - the default datastore identity is `default`
 - browser projects start with `desktop`
+- browser projects can be strings or named project objects with `type`, `device`, `viewport`, `contextOptions`, and `launchOptions`
+- browser failure artifacts store screenshots and current URLs by default, while traces and videos are opt-in
+- mail capture previews use the `mail` layout by default, matching the current `sails-hook-mail` convention
+- apps with a different mail layout can set `sounding.mail.layout`, for example `layout-email`
 - `inherit` remains available when an app already has a serious test datastore story
 
 For example:
@@ -48,6 +98,291 @@ module.exports.sounding = {
 
 If you intentionally want Sounding during another boot path, widen the list explicitly, for example `['test', 'console']` or `['test', 'production']`.
 
+## Upload trials
+
+Use HTTP request trials for Sails file uploads. Uploads in Sails are streaming
+Skipper requests, so they need the HTTP stack that Sails uses for real multipart
+forms.
+
+```js
+const { test } = require('sounding')
+
+test(
+  'creator can upload a receipt',
+  { transport: 'http' },
+  async ({ request, expect }) => {
+    const form = new FormData()
+
+    form.append('description', 'Home office monitor')
+    form.append('amount', '1200')
+    form.append(
+      'receipt',
+      new Blob(['receipt bytes'], { type: 'application/pdf' }),
+      'receipt.pdf'
+    )
+
+    const response = await request.post('/expenses', form)
+
+    expect(response).toRedirectTo('/expenses/new')
+  }
+)
+```
+
+When a multipart form mixes text fields and files, append the text fields before
+the files. That matches Sails and Skipper's streaming model, where actions can
+start while file streams are still arriving.
+
+Do not use the virtual transport for upload behavior. Virtual requests are still
+right for normal endpoints, JSON APIs, session assertions, redirects, and
+Inertia contracts, but real `req.file()` uploads are HTTP-only in Sails.
+
+## Project init
+
+Use the initializer from a Sails app to add the first Sounding test lane:
+
+```sh
+npx sounding init
+```
+
+It updates `package.json`, creates `tests/factories`, `tests/scenarios`, and `tests/sounding`, and writes starter examples without overwriting existing files. The default setup relies on Sounding's built-in conventions, so it skips `config/sounding.js` unless you ask for an editable config scaffold:
+
+```sh
+npx sounding init --config
+```
+
+Typical output looks like:
+
+```txt
+Sounding initialized /path/to/my-sails-app
+Auth convention: User
+~ Updated package.json (added `npm test`, added `sounding` devDependency, added `sails-sqlite` devDependency)
++ Created tests
++ Created tests/factories
++ Created tests/scenarios
++ Created tests/sounding
++ Created tests/factories/user.js
++ Created tests/scenarios/signed-in-user.js
++ Created tests/sounding/examples.test.js
+- Skipped config/sounding.js because Sounding defaults are enough
+
+Next: run npm install, then npm test.
+```
+
+## CLI test runner
+
+Run a Sounding suite with the framework-level runner:
+
+```sh
+npx sounding test
+```
+
+The command discovers `.test.js` files under `tests/` and `test/`, then runs Node's native test runner with Sounding-friendly filters:
+
+```sh
+npx sounding test --grep "dashboard"
+npx sounding test --file tests/sounding/examples.test.js
+npx sounding test --lane browser
+npx sounding test --watch
+```
+
+Common Node test flags pass through, and CI reporters are available without memorizing the longer Node flag names:
+
+```sh
+npx sounding test --reporter spec
+npx sounding test --junit reports/sounding-junit.xml
+npx sounding test --json
+npx sounding test --coverage
+```
+
+Use `--dry-run` to inspect the exact `node --test` command before running it.
+
+## App lifecycle
+
+Sounding keeps a warm Sails app by default. Virtual request trials load the app without opening an HTTP listener, while HTTP, socket, and browser-capable trials lift the app so the network stack exists.
+
+The app manager makes those lanes explicit:
+
+```js
+const { createAppManager } = require('sounding')
+
+const manager = createAppManager()
+
+const virtualRuntime = await manager.runtime({ app: 'load' })
+const httpRuntime = await manager.runtime({ app: 'lift' })
+const alsoHttpRuntime = await manager.runtime({ transport: 'http' })
+```
+
+Use the warm default for most suites. When a trial mutates process-global app state and needs a fresh Sails instance, force a reload:
+
+```js
+const freshRuntime = await manager.runtime({ app: 'load', reload: true })
+```
+
+Lifecycle timings are available for diagnostics:
+
+```js
+console.log(manager.lifecycle.load.durationMs)
+console.log(manager.lifecycle.lift.status)
+```
+
+Set `SOUNDING_LIFECYCLE=verbose` or `SOUNDING_DIAGNOSTICS=verbose` to print app load/lift timing messages while the suite runs.
+
+## Concurrent trials
+
+Sounding runs trials serially by default. That keeps shared Sails app state boring while request sessions, worlds, mailboxes, sockets, and browser sessions continue to reset between trials.
+
+Independent trials can opt into Node test concurrency:
+
+```js
+test.concurrent('health check is isolated', async ({ get, expect }) => {
+  const response = await get('/health')
+
+  expect(response).toHaveStatus(200)
+})
+
+test('dashboard contract is isolated too', { concurrent: true }, async ({ visit, expect }) => {
+  const page = await visit('/dashboard')
+
+  expect(page).toBeInertiaPage('dashboard/index')
+})
+```
+
+Concurrent Sounding trials bypass the global serial queue and receive isolated runtime state. Their request session, mailbox, world, sockets, and browser manager are separate from other concurrent trials. Managed SQLite datastore paths remain isolated by worker using `.tmp/db/<identity>/worker-<token>.db`, where the worker token comes from `SOUNDING_WORKER_INDEX`, `PLAYWRIGHT_WORKER_INDEX`, `TEST_WORKER_INDEX`, or the process id.
+
+Use concurrent mode for trials that do not mutate process-global app state. If you build a custom `createTestApi({ runtime })`, pass a runtime factory such as `() => createRuntime(sails)` for concurrent trials; a single shared runtime object stays serial-only.
+
+## Typing and editor support
+
+Sounding is JSDoc-first today. The public API types live beside the CommonJS source, with shared typedefs in `lib/types.js`, so JavaScript Sails apps get autocomplete and inline docs without a separate hand-maintained declaration surface.
+
+The type smoke test in `typecheck/public-api-smoke.js` checks the exported API that consumers use: `test()`, request and visit clients, worlds, mail, auth, browser, socket helpers, runtime factories, and default config. Run it with:
+
+```sh
+npm run typecheck
+```
+
+Sounding does not ship hand-written `.d.ts` files right now. If TypeScript consumers need declaration files later, they should be generated from the JSDoc source of truth and verified against the same public API smoke test.
+
+## Browser projects
+
+Browser trials start on the `desktop` project:
+
+```js
+test('subscriber can read a gated issue', { browser: true }, async ({ page }) => {
+  await page.goto('/issues/the-nerve-to-build')
+})
+```
+
+Use a string when a trial needs a named project:
+
+```js
+test('mobile navigation opens the account menu', { browser: 'mobile' }, async ({ page }) => {
+  await page.goto('/dashboard')
+})
+```
+
+Configure named projects in `config/sounding.js` when an app needs mobile devices, WebKit, or custom context options:
+
+```js
+module.exports.sounding = {
+  browser: {
+    projects: {
+      desktop: {},
+      mobile: {
+        device: 'iPhone 13'
+      },
+      safari: {
+        type: 'webkit',
+        viewport: {
+          width: 1280,
+          height: 720
+        }
+      }
+    }
+  }
+}
+```
+
+The object form stays Sails-simple while still passing through to Playwright where it matters.
+
+## Browser failure artifacts
+
+Browser-capable trials should be easy to debug without turning every run into a heavyweight recording session.
+
+By default, a failed `{ browser: true }` trial writes:
+
+- `current-url.txt`
+- `screenshot.png`
+
+under a stable, readable directory:
+
+```txt
+.tmp/sounding/artifacts/<trial-name>/<browser-project>/
+```
+
+For a trial named `dashboard shows owner stats` on the default `desktop` project, that becomes:
+
+```txt
+.tmp/sounding/artifacts/dashboard-shows-owner-stats/desktop/
+```
+
+When a failure happens, Sounding appends the current URL and artifact paths to the thrown error so the terminal output points straight at the evidence.
+
+Traces and videos are intentionally off by default because they cost more disk and time. Turn them on for a whole app:
+
+```js
+module.exports.sounding = {
+  browser: {
+    artifacts: {
+      trace: true,
+      video: true
+    }
+  }
+}
+```
+
+Or scope them to one suspicious trial:
+
+```js
+test(
+  'checkout keeps the cart after refresh',
+  {
+    browser: {
+      artifacts: {
+        trace: true,
+        video: true
+      }
+    }
+  },
+  async ({ page, expect }) => {
+    await page.goto('/checkout')
+    await page.reload()
+
+    await expect(page.getByText('Your cart')).toBeVisible()
+  }
+)
+```
+
+Use `false` as a concise off switch:
+
+```js
+test('fast smoke flow', { browser: { artifacts: false } }, async ({ page }) => {
+  await page.goto('/health')
+})
+```
+
+For artifact settings, `true` means “keep this when the trial fails.” If you need an artifact on successful browser trials too, use `on` instead:
+
+```js
+module.exports.sounding = {
+  browser: {
+    artifacts: {
+      trace: 'on'
+    }
+  }
+}
+```
+
 This repository starts with docs-driven product research and the first hook/runtime scaffolding for that vision.
 
 See `RESEARCH.md`.

package/bin/sounding.js

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+
+const { initProject } = require('../lib/init-project')
+const { formatTestCommand, runTests } = require('../lib/test-runner')
+
+function printHelp() {
+  process.stdout.write(`Sounding
+
+Usage:
+  sounding init [--app <path>] [--config]
+  sounding test [options] [files or folders]
+
+Commands:
+  init      Scaffold Sounding tests, worlds, and package scripts in a Sails app.
+  test      Run Sounding trials through the Node.js test runner.
+
+Options:
+  --app     Target app directory. Defaults to the current working directory.
+  --config  Also create config/sounding.js when it does not already exist.
+  --help    Show this help.
+`)
+}
+
+function printTestHelp() {
+  process.stdout.write(`Sounding test
+
+Usage:
+  sounding test [options] [files or folders]
+
+Options:
+  --app <path>                   Target app directory.
+  --grep <pattern>               Forward to --test-name-pattern.
+  --file <path>                  Run one file. May be repeated.
+  --lane <name>                  Run tests under tests/<name> or test/<name>.
+  --changed                      Run changed .test.js files when git metadata is available.
+  --watch                        Forward to Node watch mode.
+  --reporter <name>              Forward to --test-reporter.
+  --reporter-destination <path>  Forward to --test-reporter-destination.
+  --junit [path]                 Use the junit reporter.
+  --json                         Use the json reporter.
+  --coverage                     Enable Node test coverage.
+  --dry-run                      Print the Node command without running it.
+
+Unknown --test-* and Node flags pass through to node.
+`)
+}
+
+function parseArgs(argv) {
+  const args = [...argv]
+  const options = {}
+  const command = args.shift()
+
+  if (command === '--help' || command === '-h') {
+    return {
+      command: null,
+      options: {
+        help: true,
+      },
+    }
+  }
+
+  if (command === 'test') {
+    return {
+      command,
+      options: {
+        argv: args,
+      },
+    }
+  }
+
+  while (args.length > 0) {
+    const arg = args.shift()
+
+    if (arg === '--help' || arg === '-h') {
+      options.help = true
+      continue
+    }
+
+    if (arg === '--config') {
+      options.config = true
+      continue
+    }
+
+    if (arg === '--app') {
+      options.appPath = args.shift()
+      if (!options.appPath) {
+        throw new Error('Sounding option `--app` requires a path.')
+      }
+      continue
+    }
+
+    throw new Error(`Unknown Sounding option: ${arg}`)
+  }
+
+  return {
+    command,
+    options,
+  }
+}
+
+function printInitResult(result) {
+  process.stdout.write(`Sounding initialized ${result.appPath}\n`)
+  process.stdout.write(
+    `Auth convention: ${result.auth.modelName}${result.auth.detected ? '' : ' (default)'}\n`
+  )
+
+  for (const action of result.actions) {
+    const marker = action.type === 'created' ? '+' : action.type === 'updated' ? '~' : '-'
+    process.stdout.write(`${marker} ${action.message}\n`)
+  }
+
+  process.stdout.write('\nNext: run npm install, then npm test.\n')
+}
+
+async function main() {
+  const { command, options } = parseArgs(process.argv.slice(2))
+
+  if (!command || options.help) {
+    printHelp()
+    return
+  }
+
+  if (command === 'init') {
+    const result = initProject(options)
+    printInitResult(result)
+    return
+  }
+
+  if (command === 'test') {
+    if (options.argv.includes('--help') || options.argv.includes('-h')) {
+      printTestHelp()
+      return
+    }
+
+    const result = await runTests({
+      argv: options.argv,
+      stdio: 'inherit',
+    })
+
+    if (result.command.dryRun) {
+      process.stdout.write(`${formatTestCommand(result.command)}\n`)
+    }
+
+    process.exitCode = result.status
+    return
+  }
+
+  {
+    throw new Error(`Unknown Sounding command: ${command}`)
+  }
+}
+
+main().catch((error) => {
+  process.stderr.write(`${error.message}\n`)
+  process.exitCode = 1
+})

package/index.js

@@ -9,15 +9,27 @@ 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 { createSocketManager } = require('./lib/create-socket-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')
 
+/** @typedef {import('./lib/types').SoundingSailsApp} SoundingSailsApp */
+/** @typedef {import('./lib/types').SoundingSailsHook} SoundingSailsHook */
+
+/**
+ * @param {SoundingSailsApp} sails
+ * @returns {string | undefined}
+ */
 function getCurrentEnvironment(sails) {
   return sails.config?.environment || process.env.NODE_ENV
 }
 
+/**
+ * @param {SoundingSailsApp} sails
+ * @returns {string[]}
+ */
 function getEnabledEnvironments(sails) {
   const configured = sails.config?.sounding?.environments
 
@@ -28,10 +40,20 @@ function getEnabledEnvironments(sails) {
   return getDefaultConfig().environments
 }
 
+/**
+ * @param {SoundingSailsApp} sails
+ * @returns {boolean}
+ */
 function shouldEnableHook(sails) {
   return getEnabledEnvironments(sails).includes(getCurrentEnvironment(sails))
 }
 
+/**
+ * Sails hook factory.
+ *
+ * @param {SoundingSailsApp} sails
+ * @returns {SoundingSailsHook}
+ */
 function soundingHook(sails) {
   const runtime = createRuntime(sails)
 
@@ -79,6 +101,7 @@ module.exports.createHelperRunner = createHelperRunner
 module.exports.createRequestClient = createRequestClient
 module.exports.createVisitClient = createVisitClient
 module.exports.createBrowserManager = createBrowserManager
+module.exports.createSocketManager = createSocketManager
 module.exports.createAuthHelpers = createAuthHelpers
 module.exports.createExpect = createExpect
 module.exports.createTestApi = createTestApi