@ossy/platform 3.9.0 → 3.11.1

package/src/test/flow-runner.js

@@ -15,20 +15,36 @@ import { Router } from '@ossy/router'
 import { Schema } from '@ossy/schema'
 import { test, expect } from '@playwright/test'
 import {
+  applyFormFieldOverrides,
   escapeCssAttrValue,
   interpolateContextString,
   resolveContextValue,
 } from './flow-context.js'
+import { actionSelector, resolveActionId, resolveActionMatchers, resolveActionService } from './flow-action.js'
 import { resolveClickTarget } from './flow-click.js'
+import { assertDownloadFilenames, resolveDownloadTarget } from './flow-download.js'
+import { resolveFilesTarget } from './flow-files.js'
 import { resolvePressKey } from './flow-press.js'
 import { resolveViewportSize } from './flow-viewport.js'
 
 export {
+  applyFormFieldOverrides,
   escapeCssAttrValue,
   interpolateContextString,
   resolveContextValue,
 } from './flow-context.js'
+export {
+  actionSelector,
+  resolveActionId,
+  resolveActionMatchers,
+  resolveActionService,
+} from './flow-action.js'
 export { resolveClickTarget } from './flow-click.js'
+export {
+  assertDownloadFilenames,
+  resolveDownloadTarget,
+} from './flow-download.js'
+export { resolveFilesTarget } from './flow-files.js'
 export { resolvePressKey } from './flow-press.js'
 export { resolveViewportSize } from './flow-viewport.js'
 
@@ -92,15 +108,20 @@ function schemaEngineFromManifest (manifest) {
 }
 
 /**
- * Mock form field values via Schema.mock and update the run context.
+ * Mock form field values via Schema.mock, apply optional overrides, and update the run context.
  *
  * @param {import('@ossy/schema').Schema} engine
  * @param {{ id: string, fields?: { name: string, type?: string }[] }} template
  * @param {FlowRunContext} context
+ * @param {Record<string, unknown>} [fieldOverrides]
  */
-function mockFormContent (engine, template, context) {
-  const content = engine.mock(template, { faker })
+function mockFormContent (engine, template, context, fieldOverrides) {
+  const mocked = engine.mock(template, { faker })
+  const content = applyFormFieldOverrides(mocked, fieldOverrides, context)
   for (const field of template.fields ?? []) {
+    // Skip upload/reference mocks — they are not DOM-fillable and must not be
+    // restored onto file inputs during remount-safe action submits.
+    if (['file', 'image', 'reference'].includes(field.type)) continue
     const value = content[field.name]
     if (value !== undefined) context.fields[field.name] = value
     if (field.type === 'email' || field.name?.toLowerCase?.().includes('email')) {
@@ -110,23 +131,6 @@ function mockFormContent (engine, template, context) {
   return content
 }
 
-function resolveActionId (action) {
-  if (typeof action === 'string') return action
-  if (action && typeof action.id === 'string') return action.id
-  throw new Error('Flow action step requires an action POJO or id string')
-}
-
-function actionSelector (actionId, service) {
-  return service
-    ? `[data-action="${actionId}"][data-service="${service}"]`
-    : `[data-action="${actionId}"]`
-}
-
-function resolveActionService (action, fallback) {
-  if (typeof action === 'object' && action.service) return action.service
-  return fallback
-}
-
 function resolveContextObject (obj, context) {
   if (!obj || typeof obj !== 'object') return obj
   const out = {}
@@ -232,6 +236,67 @@ export async function runFlow (flow, options = {}) {
       continue
     }
 
+    if (step.files != null) {
+      if (!page) throw new Error('files step requires a Playwright page')
+      const { selector, payloads } = resolveFilesTarget(step.files)
+      const resolvedSelector = interpolateContextString(selector, context, {
+        escape: escapeCssAttrValue,
+      })
+      const locator = page.locator(resolvedSelector).first()
+      const filesTimeout = step.timeout ?? 15000
+      // File inputs are often visually hidden behind dropzones — attach is enough.
+      await locator.waitFor({ state: 'attached', timeout: filesTimeout })
+      // SSR markup is attached before React wires onChange. Settle like action clicks.
+      await page.evaluate(async () => {
+        await new Promise((resolve) => {
+          requestAnimationFrame(() => requestAnimationFrame(resolve))
+        })
+        await new Promise((resolve) => setTimeout(resolve, 500))
+      })
+
+      // Path payloads use Playwright's setInputFiles. In-memory buffer payloads use
+      // DataTransfer — Playwright setInputFiles populates input.files but does not
+      // notify React 19's onChange for this input; assigning via DataTransfer + change does.
+      const pathPayloads = payloads.filter((p) => typeof p === 'string')
+      const bufferPayloads = payloads.filter((p) => typeof p === 'object' && p != null)
+      if (pathPayloads.length) {
+        await locator.setInputFiles(pathPayloads)
+      }
+      if (bufferPayloads.length) {
+        await locator.evaluate((el, files) => {
+          if (!(el instanceof HTMLInputElement) || el.type !== 'file') {
+            throw new Error('files step selector must resolve to an HTML file input')
+          }
+          const dt = new DataTransfer()
+          for (const file of files) {
+            const bytes = Uint8Array.from(atob(file.base64), (c) => c.charCodeAt(0))
+            dt.items.add(new File([bytes], file.name, { type: file.mimeType }))
+          }
+          el.files = dt.files
+          el.dispatchEvent(new Event('input', { bubbles: true }))
+          el.dispatchEvent(new Event('change', { bubbles: true }))
+        }, bufferPayloads.map((p) => ({
+          name: p.name,
+          mimeType: p.mimeType,
+          base64: Buffer.from(p.buffer).toString('base64'),
+        })))
+      } else if (pathPayloads.length) {
+        // Paths-only: nudge change in case the host needs an explicit event.
+        await locator.evaluate((el) => {
+          if (!(el instanceof HTMLInputElement) || el.type !== 'file') return
+          el.dispatchEvent(new Event('input', { bubbles: true }))
+          el.dispatchEvent(new Event('change', { bubbles: true }))
+        }).catch(() => {})
+      }
+
+      // Capture the first uploaded filename for later result assertions.
+      const firstName = typeof payloads[0] === 'string'
+        ? path.basename(payloads[0])
+        : payloads[0]?.name
+      if (firstName) context.uploadedFileName = firstName
+      continue
+    }
+
     if (step.form) {
       if (!page) throw new Error('form step requires a Playwright page')
       const formMeta = step.form
@@ -245,11 +310,13 @@ export async function runFlow (flow, options = {}) {
         throw new Error(`Resource schema "${schemaId}" not found or has no fields`)
       }
       const engine = schemaEngineFromManifest(manifest)
-      const content = mockFormContent(engine, template, context)
+      // Optional field overrides: `{ form: SignInForm, fields: { email: '$email' } }`
+      const content = mockFormContent(engine, template, context, step.fields)
       const formTimeout = step.timeout ?? 15000
       const formRoot = formId ? page.locator(`form[id="${formId}"]`) : page
       await formRoot.waitFor({ state: 'visible', timeout: formTimeout })
-      for (const field of template.fields) {
+
+      const fillField = async (field) => {
         const value = content[field.name]
         if (value === undefined || value === null) {
           throw new Error(`mockFormContent produced no value for field "${field.name}"`)
@@ -259,54 +326,261 @@ export async function runFlow (flow, options = {}) {
         const tag = await locator.evaluate(el => el.tagName.toLowerCase()).catch(() => 'input')
         if (tag === 'select') {
           await locator.selectOption(String(value))
-        } else if (tag === 'input') {
+          return
+        }
+        if (tag === 'input') {
           const inputType = await locator.getAttribute('type')
           if (inputType === 'checkbox') {
             if (value) await locator.check()
-          } else {
-            // Retry fills: early hydration can accept DOM input then wipe on re-render.
-            const asText = String(value)
-            for (let attempt = 0; attempt < 3; attempt++) {
-              await locator.fill(asText)
-              try {
-                await expectFn(locator).toHaveValue(asText, { timeout: 2000 })
-                break
-              } catch (err) {
-                if (attempt === 2) throw err
-                await page.waitForTimeout(150)
-              }
-            }
+            else await locator.uncheck()
+            return
+          }
+        }
+        // Retry fills: early hydration / sibling controlled updates can wipe earlier fields.
+        const asText = String(value)
+        for (let attempt = 0; attempt < 3; attempt++) {
+          await locator.fill(asText)
+          // Blur so React controlled state commits before the next field fill.
+          await locator.blur().catch(() => {})
+          try {
+            await expectFn(locator).toHaveValue(asText, { timeout: 2000 })
+            return
+          } catch (err) {
+            if (attempt === 2) throw err
+            await page.waitForTimeout(150)
+          }
+        }
+      }
+
+      // File / reference / image fields need real uploads — skip in declarative fills.
+      const fillableFields = (template.fields ?? []).filter(
+        (field) => !['file', 'image', 'reference'].includes(field.type),
+      )
+
+      for (const field of fillableFields) {
+        await fillField(field)
+      }
+
+      // Sibling controlled re-renders can clear earlier inputs after later fills —
+      // re-assert text-like fields and repair any that drifted.
+      for (let settle = 0; settle < 3; settle++) {
+        let drifted = false
+        for (const field of fillableFields) {
+          const value = content[field.name]
+          if (value === undefined || value === null) continue
+          const locator = formRoot.locator(`[name="${field.name}"]`).first()
+          const tag = await locator.evaluate(el => el.tagName.toLowerCase()).catch(() => 'input')
+          if (tag === 'select') continue
+          if (tag === 'input') {
+            const inputType = await locator.getAttribute('type')
+            if (inputType === 'checkbox' || inputType === 'file') continue
+          }
+          const asText = String(value)
+          const current = await locator.inputValue().catch(() => '')
+          if (current !== asText) {
+            drifted = true
+            await fillField(field)
           }
-        } else {
-          await locator.fill(String(value))
         }
+        if (!drifted) break
+        if (settle === 2) {
+          throw new Error(`form step could not keep field values stable for "${formId}"`)
+        }
+        await page.waitForTimeout(150)
       }
       continue
     }
 
     if (step.action != null) {
       if (!page) throw new Error('action step requires a Playwright page')
-      const actionId = resolveActionId(step.action)
-      const service = resolveActionService(step.action, step.service)
-      const matches = page.locator(actionSelector(actionId, service))
+      const actionStep = typeof step.action === 'object' && step.action != null
+        ? resolveContextObject(step.action, context)
+        : step.action
+      const actionId = resolveActionId(actionStep)
+      const matchers = resolveActionMatchers(actionStep, {
+        service: resolveContextValue(step.service, context),
+        memberEmail: resolveContextValue(step.memberEmail, context),
+        language: resolveContextValue(step.language, context),
+      })
+      const selector = actionSelector(actionId, matchers)
       const actionTimeout = step.timeout ?? 15000
-      await matches.first().waitFor({ state: 'attached', timeout: actionTimeout })
+      const actionDeadline = Date.now() + actionTimeout
+      // SSR markup is visible before React attaches onClick. Wait for visibility,
+      // then click: form submits use remount-safe evaluate + requestSubmit; other
+      // CTAs use Playwright click (programmatic el.click() often skips React onClick).
+      //
+      // Re-query the live node after settle: concurrent auth/workspace fetches can
+      // remount the tree and detach Playwright locators mid-scroll (and wipe
+      // uncontrolled form state). Retry within the action timeout.
       // Prefer an actionable match when duplicates exist (e.g. hero CTA under a page overlay).
-      const count = await matches.count()
       let clicked = false
       let lastError
-      for (let i = 0; i < count; i++) {
-        const candidate = matches.nth(i)
+      while (!clicked && Date.now() < actionDeadline) {
+        const remaining = Math.max(250, actionDeadline - Date.now())
+        const matches = page.locator(selector)
         try {
-          await candidate.click({ timeout: Math.min(5000, actionTimeout) })
-          clicked = true
-          break
+          await matches.first().waitFor({ state: 'attached', timeout: remaining })
         } catch (err) {
           lastError = err
+          break
+        }
+        const count = await matches.count()
+        for (let i = 0; i < count; i++) {
+          const candidate = matches.nth(i)
+          try {
+            await candidate.waitFor({
+              state: 'visible',
+              timeout: Math.min(5000, Math.max(250, actionDeadline - Date.now())),
+            })
+            const fieldRestore = { ...(context.fields ?? {}) }
+            if (context.email != null && fieldRestore.email == null) {
+              fieldRestore.email = context.email
+            }
+            // Form submits: restore fills + requestSubmit in one evaluate (remount-safe).
+            // Other CTAs (Enable, Publish, OpenExport): Playwright click — programmatic
+            // el.click() often never invokes React onClick (no /actions POST; publish stays off).
+            const isSubmitButton = await candidate.evaluate((el) => {
+              const form = (el instanceof HTMLButtonElement || el instanceof HTMLInputElement)
+                ? el.form
+                : el.closest?.('form')
+              if (!form) return false
+              return (el instanceof HTMLButtonElement || el instanceof HTMLInputElement)
+                ? el.type === 'submit'
+                : el.getAttribute?.('type') === 'submit'
+            })
+            if (isSubmitButton) {
+              await page.evaluate(async ({ selector: sel, fields }) => {
+                await new Promise((resolve) => {
+                  requestAnimationFrame(() => requestAnimationFrame(resolve))
+                })
+                await new Promise((resolve) => setTimeout(resolve, 500))
+                const el = document.querySelector(sel)
+                if (!el) throw new Error(`Action control disappeared after settle: ${sel}`)
+                if (typeof el.scrollIntoView === 'function') {
+                  el.scrollIntoView({ block: 'nearest', inline: 'nearest' })
+                }
+                const form = (el instanceof HTMLButtonElement || el instanceof HTMLInputElement)
+                  ? el.form
+                  : el.closest?.('form')
+                if (form && fields && typeof fields === 'object') {
+                  for (const [name, value] of Object.entries(fields)) {
+                    if (value == null || typeof value === 'object') continue
+                    const input = form.querySelector(`[name="${name}"]`)
+                    if (!input || input.disabled) continue
+                    if (input instanceof HTMLInputElement && input.type === 'file') continue
+                    const asText = String(value)
+                    if (input.value === asText) continue
+                    const proto = Object.getPrototypeOf(input)
+                    const desc = Object.getOwnPropertyDescriptor(proto, 'value')
+                    desc?.set?.call(input, asText)
+                    input.dispatchEvent(new Event('input', { bubbles: true }))
+                    input.dispatchEvent(new Event('change', { bubbles: true }))
+                  }
+                }
+                if (form && typeof form.requestSubmit === 'function') {
+                  form.requestSubmit(el)
+                  return
+                }
+                if (typeof el.click === 'function') el.click()
+              }, { selector, fields: fieldRestore })
+            } else {
+              await candidate.scrollIntoViewIfNeeded().catch(() => {})
+              await candidate.click({
+                timeout: Math.min(5000, Math.max(250, actionDeadline - Date.now())),
+              })
+            }
+            clicked = true
+            break
+          } catch (err) {
+            lastError = err
+            const message = String(err?.message ?? err)
+            if (/not attached|disappeared after settle/i.test(message)) {
+              await page.waitForTimeout(100)
+              break
+            }
+          }
+        }
+        if (!clicked && Date.now() < actionDeadline) {
+          await page.waitForTimeout(100)
         }
       }
       if (!clicked) {
-        throw lastError ?? new Error(`No actionable locator for ${actionSelector(actionId, service)}`)
+        throw lastError ?? new Error(`No actionable locator for ${selector}`)
+      }
+      continue
+    }
+
+    if (step.download != null) {
+      if (!page) throw new Error('download step requires a Playwright page')
+      const target = resolveDownloadTarget(step.download)
+      const timeout = step.timeout ?? target.timeout
+      const locator = target.actionId
+        ? page.locator(actionSelector(target.actionId, target.service))
+        : page.locator(target.selector)
+      await locator.first().waitFor({ state: 'visible', timeout })
+
+      // Collect downloads via one listener — parallel waitForEvent('download')
+      // waiters all resolve on the *first* event (Playwright EventEmitter fan-out).
+      const downloads = []
+      const onDownload = (download) => {
+        downloads.push(download)
+      }
+      page.on('download', onDownload)
+      try {
+        await locator.first().scrollIntoViewIfNeeded()
+        await locator.first().click({ timeout })
+        const deadline = Date.now() + timeout
+        while (downloads.length < target.count) {
+          if (Date.now() > deadline) {
+            throw new Error(
+              `Timed out waiting for ${target.count} download(s); got ${downloads.length}`,
+            )
+          }
+          await page.waitForTimeout(50)
+        }
+      } finally {
+        page.off('download', onDownload)
+      }
+
+      const suggested = downloads.slice(0, target.count).map((download) => download.suggestedFilename())
+      assertDownloadFilenames(suggested, target.filenames)
+      context.downloads = suggested
+      if (suggested[0]) context.downloadedFileName = suggested[0]
+      continue
+    }
+
+    if (step.inputs != null) {
+      if (!page) throw new Error('inputs step requires a Playwright page')
+      const inputsTimeout = step.timeout ?? 15000
+      for (const [selector, valueSpec] of Object.entries(step.inputs)) {
+        const value = resolveContextValue(valueSpec, context)
+        if (value == null) {
+          throw new Error(`inputs step: no value resolved for selector "${selector}"`)
+        }
+        const resolvedSelector = interpolateContextString(selector, context, {
+          escape: escapeCssAttrValue,
+        })
+        const locator = page.locator(resolvedSelector).first()
+        await locator.waitFor({ state: 'visible', timeout: inputsTimeout })
+        const asText = String(value)
+        for (let attempt = 0; attempt < 3; attempt++) {
+          await locator.fill(asText)
+          await locator.blur().catch(() => {})
+          try {
+            await expectFn(locator).toHaveValue(asText, { timeout: 2000 })
+            break
+          } catch (err) {
+            if (attempt === 2) throw err
+            await page.waitForTimeout(150)
+          }
+        }
+        // Remount-safe action submits restore from context.fields by input name.
+        // Keep ad-hoc fills (e.g. sign-in code) in that map so settle remounts
+        // do not wipe values before requestSubmit.
+        const name = await locator.getAttribute('name')
+        if (name) {
+          context.fields = { ...(context.fields ?? {}), [name]: asText }
+        }
       }
       continue
     }
@@ -340,33 +614,109 @@ export async function runFlow (flow, options = {}) {
       const to = resolveContextValue(emailStep.to ?? '$email', context)
       const templateId = emailStep.id ?? emailStep.templateId
       const clickLabel = emailStep.click ?? emailStep.link
+      const extract = emailStep.extract
       if (!to) throw new Error('email step requires "to" (recipient email)')
       if (!templateId) throw new Error('email step requires "id" (email template id)')
-      if (!clickLabel) throw new Error('email step requires "click" (link text in the email)')
+      if (!clickLabel && !extract) {
+        throw new Error('email step requires "click" or "extract"')
+      }
 
       const inboxPath = router.getPathname({ id: 'dev-inbox', language: locale }) ?? '/dev/inbox'
       const params = new URLSearchParams({ to: String(to), template: String(templateId) })
       const inboxUrl = `${baseURL}${inboxPath}?${params}`
-      const pattern = linkNamePattern(clickLabel)
       const deadline = Date.now() + (emailStep.timeout ?? 20000)
 
-      let clicked = false
-      while (Date.now() < deadline && !clicked) {
-        await page.goto(inboxUrl)
-        const link = page.getByRole('link', { name: pattern }).first()
+      const openInboxBody = async (inboxPage) => {
+        await inboxPage.goto(inboxUrl)
+        const body = inboxPage.locator('[data-email-body]').first()
+        await body.waitFor({ state: 'visible', timeout: 2000 })
+        return body
+      }
+
+      // Extract-only must not navigate the flow page — SPA React state (e.g. SignIn
+      // success + code form for PWA) is lost on goto/goBack remount.
+      if (extract && !clickLabel) {
+        const inboxPage = await page.context().newPage()
+        let extracted = false
         try {
-          await link.waitFor({ state: 'visible', timeout: 2000 })
-          await Promise.all([
-            page.waitForLoadState('domcontentloaded'),
-            link.click(),
-          ])
-          clicked = true
-        } catch {
-          await page.waitForTimeout(500)
+          while (Date.now() < deadline && !extracted) {
+            try {
+              const body = await openInboxBody(inboxPage)
+              for (const [key, spec] of Object.entries(extract)) {
+                const selector = typeof spec === 'string' ? spec : spec.selector
+                const attr = typeof spec === 'object' ? spec.attr : undefined
+                const resolvedSelector = interpolateContextString(selector, context, {
+                  escape: escapeCssAttrValue,
+                })
+                const locator = body.locator(resolvedSelector).first()
+                await locator.waitFor({ state: 'attached', timeout: 2000 })
+                const value = attr
+                  ? await locator.getAttribute(attr)
+                  : await locator.textContent()
+                context[key] = typeof value === 'string' ? value.trim() : value
+              }
+              extracted = true
+            } catch {
+              await page.waitForTimeout(500)
+            }
+          }
+        } finally {
+          await inboxPage.close().catch(() => {})
+        }
+        if (!extracted) {
+          throw new Error(`Email extract failed for to=${to}, template=${templateId}`)
         }
+        continue
       }
-      if (!clicked) {
-        throw new Error(`Email link "${clickLabel}" not found for to=${to}, template=${templateId}`)
+
+      if (extract && clickLabel) {
+        let extracted = false
+        while (Date.now() < deadline && !extracted) {
+          try {
+            const body = await openInboxBody(page)
+            for (const [key, spec] of Object.entries(extract)) {
+              const selector = typeof spec === 'string' ? spec : spec.selector
+              const attr = typeof spec === 'object' ? spec.attr : undefined
+              const resolvedSelector = interpolateContextString(selector, context, {
+                escape: escapeCssAttrValue,
+              })
+              const locator = body.locator(resolvedSelector).first()
+              await locator.waitFor({ state: 'attached', timeout: 2000 })
+              const value = attr
+                ? await locator.getAttribute(attr)
+                : await locator.textContent()
+              context[key] = typeof value === 'string' ? value.trim() : value
+            }
+            extracted = true
+          } catch {
+            await page.waitForTimeout(500)
+          }
+        }
+        if (!extracted) {
+          throw new Error(`Email extract failed for to=${to}, template=${templateId}`)
+        }
+      }
+
+      if (clickLabel) {
+        const pattern = linkNamePattern(clickLabel)
+        let clicked = false
+        while (Date.now() < deadline && !clicked) {
+          const body = await openInboxBody(page)
+          const link = body.getByRole('link', { name: pattern }).first()
+          try {
+            await link.waitFor({ state: 'visible', timeout: 2000 })
+            await Promise.all([
+              page.waitForLoadState('domcontentloaded'),
+              link.click(),
+            ])
+            clicked = true
+          } catch {
+            await page.waitForTimeout(500)
+          }
+        }
+        if (!clicked) {
+          throw new Error(`Email link "${clickLabel}" not found for to=${to}, template=${templateId}`)
+        }
       }
       continue
     }
@@ -390,9 +740,16 @@ export async function runFlow (flow, options = {}) {
         await expectFn(locator).toBeVisible({ timeout })
       }
       if (action != null) {
-        const actionId = resolveActionId(action)
-        const service = resolveActionService(action, step.result.service)
-        await assertLocator(page.locator(actionSelector(actionId, service)).first())
+        const actionResult = typeof action === 'object' && action != null
+          ? resolveContextObject(action, context)
+          : action
+        const actionId = resolveActionId(actionResult)
+        const matchers = resolveActionMatchers(actionResult, {
+          service: resolveContextValue(step.result.service, context),
+          memberEmail: resolveContextValue(step.result.memberEmail, context),
+          language: resolveContextValue(step.result.language, context),
+        })
+        await assertLocator(page.locator(actionSelector(actionId, matchers)).first())
       }
       if (selector != null) {
         const resolvedSelector = interpolateContextString(selector, context, {
@@ -463,6 +820,9 @@ export function registerFlow (mod, options = {}) {
 
   test.describe(feature, () => {
     test(title, async ({ page, baseURL }) => {
+      if (typeof meta.timeout === 'number' && meta.timeout > 0) {
+        test.setTimeout(meta.timeout)
+      }
       const manifestPath = options.manifestPath
       const manifest = manifestPath ? loadManifest(manifestPath) : undefined
       await runFlow({ ...flowBody, steps, metadata: meta }, {

package/src/test/test.util.js

@@ -173,6 +173,43 @@ export class TestUtil {
     return ev.payload.token
   }
 
+  /**
+   * Resolve a six-digit sign-in code from its stored HMAC digest (integration tests only).
+   *
+   * @param {string} subjectId
+   * @returns {Promise<string>}
+   */
+  static async getLatestVerificationCodeForSubject(subjectId) {
+    const ev = await EventStore.Collection.findOne(
+      {
+        type: TOKEN_SCHEMA,
+        event: 'Created',
+        'payload.type': 'Verification',
+        'payload.subject': subjectId,
+      },
+      { sort: { created: -1 } },
+    )
+    const codeHash = ev?.payload?.codeHash
+    if (!codeHash) {
+      return Promise.reject(new Error('No verification code hash found for subject'))
+    }
+
+    const secret = process.env.TOKEN_SECRET
+    if (!secret) {
+      return Promise.reject(new Error('TOKEN_SECRET is required to resolve verification codes in tests'))
+    }
+
+    const { createHmac } = await import('node:crypto')
+    const hashCode = (code) => createHmac('sha256', secret).update(code).digest('hex')
+
+    for (let i = 0; i < 1_000_000; i += 1) {
+      const code = String(i).padStart(6, '0')
+      if (hashCode(code) === codeHash) return code
+    }
+
+    return Promise.reject(new Error('Could not resolve verification code from hash'))
+  }
+
   static async getLatestEmailChangeJwtForSubject(subjectId) {
     const ev = await EventStore.Collection.findOne(
       {