chore(tests): ratchet real wall-clock waits in unit tests

.claude/rules/sim-testing.md

@@ -169,6 +169,7 @@ The suite's wall time is bound by the single Vite server thread that serves ever
 3. Mock heavy graphs a test does not need and the setup does not already mock: `@/blocks`,
    `@/triggers/registry`, `@/tools/generated/*`.
 4. No real timers: `vi.useFakeTimers()`, `flushMicrotasks()`, or `flushMacrotask()`.
+   `check:test-patterns` (`real-wait`) fails on a new wall-clock wait in a unit test.
 5. Absolute imports only.
 
 ### Running

.cursor/rules/sim-testing.mdc

@@ -167,6 +167,7 @@ The suite's wall time is bound by the single Vite server thread that serves ever
 3. Mock heavy graphs a test does not need and the setup does not already mock: `@/blocks`,
    `@/triggers/registry`, `@/tools/generated/*`.
 4. No real timers: `vi.useFakeTimers()`, `flushMicrotasks()`, or `flushMacrotask()`.
+   `check:test-patterns` (`real-wait`) fails on a new wall-clock wait in a unit test.
 5. Absolute imports only.
 
 ### Running

scripts/check-test-patterns.test.ts

@@ -1,5 +1,9 @@
 import { describe, expect, it } from 'vitest'
-import { findStubAndHookViolations, parseSource } from './check-test-patterns'
+import {
+  findRealWaitViolations,
+  findStubAndHookViolations,
+  parseSource,
+} from './check-test-patterns'
 
 function rules(source: string, file = 'apps/sim/lib/example.test.ts') {
   return findStubAndHookViolations(file, parseSource(file, source)).map(
@@ -76,3 +80,308 @@ describe('redundant-hook', () => {
     ])
   })
 })
+
+describe('real-wait', () => {
+  const HELPERS = "import { sleep, interruptibleSleep } from '@sim/utils/helpers'"
+
+  function waits(source: string, file = 'apps/sim/lib/example.test.ts') {
+    return findRealWaitViolations(file, parseSource(file, source)).map(({ detail }) => detail)
+  }
+
+  it.each<[string, string[], string[]]>([
+    ['an imported sleep', [HELPERS, "it('t', async () => { await sleep(10) })"], ['sleep() #1']],
+    [
+      'an aliased sleep',
+      ["import { sleep as wait } from '@sim/utils/helpers'", 'await wait(10)'],
+      ['sleep() #1'],
+    ],
+    [
+      'interruptibleSleep',
+      [HELPERS, 'await interruptibleSleep(10, signal)'],
+      ['interruptibleSleep() #1'],
+    ],
+    ['a sleep with a computed delay', [HELPERS, 'await sleep(delayMs)'], ['sleep() #1']],
+    [
+      'timers/promises setTimeout',
+      ["import { setTimeout as delay } from 'node:timers/promises'", 'await delay(50)'],
+      ['timers/promises setTimeout() #1'],
+    ],
+    [
+      'a promise resolved by setTimeout',
+      ['await new Promise((r) => setTimeout(r, 5))'],
+      ['setTimeout promise #1'],
+    ],
+    [
+      'a promise resolved from a setTimeout callback',
+      ['await new Promise<void>((resolve) => { globalThis.setTimeout(() => resolve(), ms) })'],
+      ['setTimeout promise #1'],
+    ],
+    [
+      'fake timers that leave setTimeout real',
+      [HELPERS, "beforeEach(() => { vi.useFakeTimers({ toFake: ['Date'] }) })", 'await sleep(10)'],
+      ['sleep() #1'],
+    ],
+    [
+      'fake timers that advance with the wall clock',
+      [
+        HELPERS,
+        "it('t', async () => {",
+        '  vi.useFakeTimers({ shouldAdvanceTime: true })',
+        '  await sleep(10)',
+        '})',
+      ],
+      ['sleep() #1'],
+    ],
+    [
+      'a sleep before the test installs fake timers',
+      [HELPERS, "it('t', async () => {", '  await sleep(10)', '  vi.useFakeTimers()', '})'],
+      ['sleep() #1'],
+    ],
+    [
+      'a sleep in a test beside one that installs fake timers',
+      [
+        HELPERS,
+        "it('a', () => { vi.useFakeTimers() })",
+        "it('b', async () => { await sleep(10) })",
+      ],
+      ['sleep() #1'],
+    ],
+    [
+      'a sleep before the install in the hook that installs fake timers',
+      [
+        HELPERS,
+        "describe('d', () => {",
+        '  beforeEach(async () => {',
+        '    await sleep(100)',
+        '    vi.useFakeTimers()',
+        '  })',
+        "  it('t', async () => { await sleep(10) })",
+        '})',
+      ],
+      ['sleep() #1'],
+    ],
+    [
+      'a sleep after the test restores real timers',
+      [
+        HELPERS,
+        "it('t', async () => {",
+        '  vi.useFakeTimers()',
+        '  vi.useRealTimers()',
+        '  await sleep(10)',
+        '})',
+      ],
+      ['sleep() #1'],
+    ],
+    [
+      'a sleep in a nested suite that restores real timers',
+      [
+        HELPERS,
+        "describe('outer', () => {",
+        '  beforeEach(() => { vi.useFakeTimers() })',
+        "  describe('inner', () => {",
+        '    beforeEach(() => { vi.useRealTimers() })',
+        "    it('t', async () => { await sleep(10) })",
+        '  })',
+        '})',
+      ],
+      ['sleep() #1'],
+    ],
+    [
+      'a sleep in a beforeAll beside a beforeEach that installs fake timers',
+      [
+        HELPERS,
+        'beforeEach(() => { vi.useFakeTimers() })',
+        'beforeAll(async () => { await sleep(10) })',
+      ],
+      ['sleep() #1'],
+    ],
+    [
+      'a sleep in a beforeEach declared before the one that installs fake timers',
+      [
+        HELPERS,
+        'beforeEach(async () => { await sleep(10) })',
+        'beforeEach(() => { vi.useFakeTimers() })',
+      ],
+      ['sleep() #1'],
+    ],
+    [
+      'fake timers with a config the AST cannot read',
+      [
+        HELPERS,
+        'beforeEach(() => { vi.useFakeTimers(config) })',
+        "it('t', async () => { await sleep(10) })",
+      ],
+      ['sleep() #1'],
+    ],
+    [
+      'fake timers with a spread config',
+      [
+        HELPERS,
+        "it('t', async () => {",
+        '  vi.useFakeTimers({ ...config })',
+        '  await sleep(10)',
+        '})',
+      ],
+      ['sleep() #1'],
+    ],
+    [
+      'namespace imports',
+      [
+        "import * as helpers from '@sim/utils/helpers'",
+        "import * as timers from 'node:timers/promises'",
+        'await helpers.sleep(10)',
+        'await timers.setTimeout(10)',
+      ],
+      ['sleep() #1', 'timers/promises setTimeout() #1'],
+    ],
+    [
+      'a module-scope wait before a module-scope install',
+      [HELPERS, 'await sleep(10)', 'vi.useFakeTimers()'],
+      ['sleep() #1'],
+    ],
+    [
+      'a helper wait after module-scope real timers are restored',
+      [
+        HELPERS,
+        'async function settle() { await sleep(10) }',
+        'vi.useFakeTimers()',
+        'vi.useRealTimers()',
+      ],
+      ['sleep() #1'],
+    ],
+    [
+      'a helper called at module scope before a module-scope install',
+      [
+        HELPERS,
+        'async function settle() { await sleep(10) }',
+        'await settle()',
+        'vi.useFakeTimers()',
+      ],
+      ['sleep() #1'],
+    ],
+    [
+      'an arrow helper called at module scope before a module-scope install',
+      [
+        HELPERS,
+        'const settle = async () => { await sleep(10) }',
+        'await settle()',
+        'vi.useFakeTimers()',
+      ],
+      ['sleep() #1'],
+    ],
+    [
+      'a wrapped arrow helper called at module scope before a module-scope install',
+      [
+        HELPERS,
+        'const settle = (async () => { await sleep(10) }) satisfies (() => Promise<void>)',
+        'await settle()',
+        'vi.useFakeTimers()',
+      ],
+      ['sleep() #1'],
+    ],
+    [
+      'every occurrence, numbered per kind',
+      [HELPERS, 'await sleep(10)', 'await new Promise((r) => setTimeout(r, 5))', 'await sleep(20)'],
+      ['sleep() #1', 'setTimeout promise #1', 'sleep() #2'],
+    ],
+  ])('flags %s', (_name, lines, expected) => {
+    expect(waits(lines.join('\n'))).toEqual(expected)
+  })
+
+  it.each<[string, string[]]>([
+    [
+      'a sleep not imported from @sim/utils/helpers',
+      ["import { sleep } from './helpers'", 'await sleep(10)'],
+    ],
+    [
+      'a mocked @sim/utils/helpers',
+      [HELPERS, "vi.mock('@sim/utils/helpers', () => utilsHelpersMock)", 'await sleep(10)'],
+    ],
+    ['a zero-delay sleep', [HELPERS, 'await sleep(0)']],
+    [
+      'a zero-delay setTimeout promise',
+      ['await new Promise((r) => setTimeout(r, 0))', 'await new Promise((r) => setTimeout(r))'],
+    ],
+    [
+      'a setTimeout that only rejects',
+      [
+        "await new Promise((resolve, reject) => setTimeout(() => reject(new Error('timeout')), 50))",
+      ],
+    ],
+    [
+      'a sleep after the test installs fake timers',
+      [
+        HELPERS,
+        "it('t', async () => {",
+        '  vi.useFakeTimers()',
+        '  const done = sleep(10)',
+        '  await vi.advanceTimersByTimeAsync(10)',
+        '  await done',
+        '})',
+      ],
+    ],
+    [
+      'a sleep in a describe whose beforeEach installs fake timers',
+      [
+        HELPERS,
+        "describe('d', () => {",
+        "  beforeEach(() => { vi.useFakeTimers({ toFake: ['setTimeout'] }) })",
+        "  it('t', async () => { await sleep(10) })",
+        '})',
+      ],
+    ],
+    [
+      'a sleep under a module-level beforeAll that installs fake timers',
+      [HELPERS, "it('t', async () => { await sleep(10) })", 'beforeAll(() => vi.useFakeTimers())'],
+    ],
+    [
+      'a sleep after the install in the hook that installs fake timers',
+      [HELPERS, 'beforeAll(async () => {', '  vi.useFakeTimers()', '  await sleep(100)', '})'],
+    ],
+    [
+      'a sleep after real timers are restored and fake ones installed again',
+      [
+        HELPERS,
+        "it('t', async () => {",
+        '  vi.useRealTimers()',
+        '  vi.useFakeTimers()',
+        '  await sleep(10)',
+        '})',
+      ],
+    ],
+    [
+      'a sleep in an afterEach beside a beforeEach that installs fake timers',
+      [
+        HELPERS,
+        'beforeEach(() => { vi.useFakeTimers() })',
+        'afterEach(async () => { await sleep(10) })',
+      ],
+    ],
+    [
+      'a helper declared before a module-scope install',
+      [
+        HELPERS,
+        "vi.mock('@/lib/example', () => ({}))",
+        'const mocks = vi.hoisted(() => ({ run: vi.fn() }))',
+        'const DELAY_MS = 10',
+        'type Options = { delay: number }',
+        'async function settle() { await sleep(DELAY_MS) }',
+        'const settleLater = async () => { await settle() }',
+        'const run = vi.fn()',
+        'const fixture = createFixture()',
+        'vi.useFakeTimers()',
+        'await settle()',
+        "it('t', async () => { await settle() })",
+      ],
+    ],
+  ])('ignores %s', (_name, lines) => {
+    expect(waits(lines.join('\n'))).toEqual([])
+  })
+
+  it.each(['apps/sim/lib/example.integration.ts', 'apps/sim/tools/example.live.test.ts'])(
+    'exempts %s, which waits on real services',
+    (file) => {
+      expect(waits([HELPERS, 'await sleep(10)'].join('\n'), file)).toEqual([])
+    }
+  )
+})