@beechcms/api 0.4.0 → 0.4.2

package/src/features/automations/__tests__/automations.schema.test.ts

@@ -0,0 +1,134 @@
+import { describe, it, expect } from 'vitest'
+import {
+  createAutomationSchema,
+  updateAutomationSchema,
+  toggleAutomationSchema,
+} from '../automations.schema'
+
+const validWebhookAction = { type: 'webhook' as const, url: 'https://example.com/hook' }
+
+const minimalValid = {
+  seed_slug: 'posts',
+  name: 'notify-on-create',
+  triggers: [{ event: 'create' as const }],
+  actions: [validWebhookAction],
+}
+
+describe('createAutomationSchema', () => {
+  it('accepts minimal valid create payload', () => {
+    expect(createAutomationSchema.safeParse(minimalValid).success).toBe(true)
+  })
+
+  it('rejects cron trigger without cron expression', () => {
+    const result = createAutomationSchema.safeParse({
+      ...minimalValid,
+      triggers: [{ event: 'cron' }],
+    })
+    expect(result.success).toBe(false)
+  })
+
+  it('accepts cron trigger with cron expression', () => {
+    const result = createAutomationSchema.safeParse({
+      ...minimalValid,
+      triggers: [{ event: 'cron', cron: '0 * * * *' }],
+    })
+    expect(result.success).toBe(true)
+  })
+
+  it('rejects duplicate trigger events', () => {
+    const result = createAutomationSchema.safeParse({
+      ...minimalValid,
+      triggers: [{ event: 'create' }, { event: 'create' }],
+    })
+    expect(result.success).toBe(false)
+  })
+
+  it('accepts multiple distinct triggers', () => {
+    const result = createAutomationSchema.safeParse({
+      ...minimalValid,
+      triggers: [{ event: 'create' }, { event: 'update' }],
+    })
+    expect(result.success).toBe(true)
+  })
+
+  it('rejects empty actions array', () => {
+    const result = createAutomationSchema.safeParse({ ...minimalValid, actions: [] })
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects unknown action type', () => {
+    const result = createAutomationSchema.safeParse({
+      ...minimalValid,
+      actions: [{ type: 'unknown_type', url: 'https://example.com' }],
+    })
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects webhook with non-url', () => {
+    const result = createAutomationSchema.safeParse({
+      ...minimalValid,
+      actions: [{ type: 'webhook', url: 'not-a-url' }],
+    })
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects send_mail with invalid email', () => {
+    const result = createAutomationSchema.safeParse({
+      ...minimalValid,
+      actions: [{ type: 'send_mail', to: 'not-an-email', subject_template: 'hi', body_template: 'body' }],
+    })
+    expect(result.success).toBe(false)
+  })
+
+  it('accepts trigger_conditions as null', () => {
+    const result = createAutomationSchema.safeParse({
+      ...minimalValid,
+      trigger_conditions: null,
+    })
+
+    expect(result.success).toBe(true)
+  })
+
+  it('accepts trigger_conditions as WhenNode', () => {
+    const result = createAutomationSchema.safeParse({
+      ...minimalValid,
+      trigger_conditions: {
+        kind: 'group',
+        op: 'AND',
+        children: [
+          { kind: 'predicate', left: { kind: 'ref', key: 'this.status' }, op: 'eq', right: { kind: 'literal', value: 'published' } },
+        ],
+      },
+    })
+    expect(result.success).toBe(true)
+  })
+})
+
+describe('updateAutomationSchema', () => {
+  it('accepts empty object', () => {
+    expect(updateAutomationSchema.safeParse({}).success).toBe(true)
+  })
+
+  it('accepts name-only without requiring triggers', () => {
+    const result = updateAutomationSchema.safeParse({ name: 'renamed' })
+    expect(result.success).toBe(true)
+  })
+})
+
+describe('toggleAutomationSchema', () => {
+  it('accepts { enabled: true }', () => {
+    expect(toggleAutomationSchema.safeParse({ enabled: true }).success).toBe(true)
+  })
+
+  it('accepts { enabled: false }', () => {
+    expect(toggleAutomationSchema.safeParse({ enabled: false }).success).toBe(true)
+  })
+
+  it('rejects missing enabled', () => {
+    expect(toggleAutomationSchema.safeParse({}).success).toBe(false)
+  })
+
+  it('rejects non-boolean enabled', () => {
+    expect(toggleAutomationSchema.safeParse({ enabled: 'true' }).success).toBe(false)
+  })
+})

package/src/features/automations/__tests__/context-resolver.test.ts

@@ -0,0 +1,122 @@
+import { describe, it, expect } from 'vitest'
+import type { Automation } from '@beechcms/core'
+import { resolveAutomationContext, deriveEntryContext } from '../context-resolver'
+import { parseTemplateKey } from '../template-grammar'
+
+function makeAutomation(overrides: Partial<Automation> = {}): Automation {
+  return {
+    id: 'auto-1',
+    seed_slug: 'orders',
+    name: 'test',
+    enabled: true,
+    triggers: [{ event: 'cron' as const, cron: '* * * * *' }],
+    trigger_conditions: null,
+    actions: [],
+    created_at: 0,
+    updated_at: 0,
+    ...overrides,
+  }
+}
+
+describe('resolveAutomationContext', () => {
+  const triggerEntry = { id: 'e1', email: 'alice@example.com', product_id: 'p1' }
+  const batchEntries = [
+    { id: 'e1', total: 10, email: 'alice@example.com' },
+    { id: 'e2', total: 20, email: 'bob@example.com' },
+    { id: 'e3', total: 30, email: 'carol@example.com' },
+  ]
+
+  it('this scope resolves to triggering entry field', async () => {
+    const ctx = await resolveAutomationContext(makeAutomation(), triggerEntry, [triggerEntry])
+    expect(ctx.lookup(parseTemplateKey('this:email')!)).toBe('alice@example.com')
+  })
+
+  it('this. dot notation resolves to triggering entry field', async () => {
+    const ctx = await resolveAutomationContext(makeAutomation(), triggerEntry, [triggerEntry])
+    expect(ctx.lookup(parseTemplateKey('email')!)).toBe('alice@example.com')
+    expect(ctx.lookup(parseTemplateKey('this:product_id')!)).toBe('p1')
+  })
+
+  it('batch:all:count matches batchEntries length', async () => {
+    const ctx = await resolveAutomationContext(makeAutomation(), triggerEntry, batchEntries)
+    expect(ctx.lookup(parseTemplateKey('batch:all:count')!)).toBe(3)
+  })
+
+  it('unknown scope → undefined + onMissing fires', async () => {
+    const ctx = await resolveAutomationContext(makeAutomation(), triggerEntry, [triggerEntry])
+    const missing: string[] = []
+    const val = ctx.lookup(parseTemplateKey('unknownseed:lastone:email')!, (f) => missing.push(f))
+    expect(val).toBeUndefined()
+    expect(missing).toHaveLength(1)
+    expect(missing[0]).toBe('unknownseed')
+  })
+
+  it('pluck truncates to 100 entries and appends truncation marker', async () => {
+    const rows = Array.from({ length: 150 }, (_, i) => ({ email: `u${i}@example.com` }))
+    const ctx = await resolveAutomationContext(makeAutomation(), triggerEntry, rows)
+    const key = parseTemplateKey('batch:all:pluck:email')!
+    const result = ctx.lookup(key) as string
+    const values = result.split(', ')
+    expect(result.endsWith(' …')).toBe(true)
+    expect(values.length).toBe(100)
+  })
+
+  it('sum on non-numeric field values returns 0 and fires onMissing for NaN', async () => {
+    const ctx = await resolveAutomationContext(
+      makeAutomation(),
+      triggerEntry,
+      [{ id: 'e1', amount: 'not-a-number' }, { id: 'e2', amount: 'also-not' }],
+    )
+    const missing: string[] = []
+    const result = ctx.lookup(parseTemplateKey('batch:all:sum:amount')!, (f) => missing.push(f))
+    expect(result).toBe(0)
+    expect(missing.length).toBeGreaterThan(0)
+  })
+
+  describe('aggregates on batch', () => {
+    const rows = [
+      { id: 'e1', total: 10 },
+      { id: 'e2', total: 20 },
+      { id: 'e3', total: 30 },
+    ]
+
+    async function makeCtx(batchRows: Record<string, unknown>[]) {
+      return resolveAutomationContext(makeAutomation(), batchRows[0] ?? null, batchRows)
+    }
+
+    it('count', async () => {
+      const ctx = await makeCtx(rows)
+      expect(ctx.lookup(parseTemplateKey('batch:all:count')!)).toBe(3)
+    })
+
+    it('sum', async () => {
+      const ctx = await makeCtx(rows)
+      expect(ctx.lookup(parseTemplateKey('batch:all:sum:total')!)).toBe(60)
+    })
+
+    it('avg', async () => {
+      const ctx = await makeCtx(rows)
+      expect(ctx.lookup(parseTemplateKey('batch:all:avg:total')!)).toBe(20)
+    })
+
+    it('min', async () => {
+      const ctx = await makeCtx(rows)
+      expect(ctx.lookup(parseTemplateKey('batch:all:min:total')!)).toBe(10)
+    })
+
+    it('max', async () => {
+      const ctx = await makeCtx(rows)
+      expect(ctx.lookup(parseTemplateKey('batch:all:max:total')!)).toBe(30)
+    })
+  })
+})
+
+describe('deriveEntryContext', () => {
+  it('this scope returns new entry, batch scope delegates to base', async () => {
+    const batchRows = [{ id: 'e1', val: 1 }, { id: 'e2', val: 2 }]
+    const base = await resolveAutomationContext(makeAutomation(), batchRows[0] ?? null, batchRows)
+    const derived = deriveEntryContext(base, { id: 'e2', val: 2, email: 'derived@example.com' })
+    expect(derived.lookup(parseTemplateKey('this:email')!)).toBe('derived@example.com')
+    expect(derived.lookup(parseTemplateKey('batch:all:count')!)).toBe(2)
+  })
+})

package/src/features/automations/__tests__/cron-runner.test.ts

@@ -0,0 +1,263 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import type { Automation, IAutomationRepository, ContentRepository, Seed, IIdGenerator } from '@beechcms/core'
+import { runCronAutomations } from '../cron-runner'
+import type { CronRunnerDeps } from '../cron-runner'
+
+vi.mock('../action-executors', () => ({
+  executeAction: vi.fn().mockResolvedValue(undefined),
+}))
+
+import { executeAction } from '../action-executors'
+const executeActionMock = executeAction as ReturnType<typeof vi.fn>
+
+// 2026-05-14T09:00:00Z → minute=0, hour=9, dow=4 (Thursday)
+const TICK = new Date('2026-05-14T09:00:00Z').getTime()
+
+const SEED: Seed = {
+  slug: 'posts',
+  label: 'Post',
+  displayNameAlias: 'title',
+  branches: [
+    { alias: 'title', type: 'text', label: 'Title' },
+    { alias: 'count', type: 'number', label: 'Count' },
+    { alias: 'published', type: 'boolean', label: 'Published' },
+    { alias: 'publish_date', type: 'date', label: 'Publish Date' },
+    { alias: 'tags_list', type: 'tags', label: 'Tags' },
+    { alias: 'meta_json', type: 'json', label: 'Meta JSON' },
+    { alias: 'body_rich', type: 'richtext', label: 'Body' },
+  ],
+}
+
+const STUB_ID_GENERATOR: IIdGenerator = {
+  uuid: () => 'test-uuid',
+}
+
+function makeAutomation(overrides: Partial<Automation> = {}): Automation {
+  return {
+    id: 'auto_01',
+    seed_slug: 'posts',
+    name: 'every-minute',
+    enabled: true,
+    triggers: [{ event: 'cron' as const, cron: '* * * * *' }],
+    trigger_conditions: null,
+    actions: [{ type: 'webhook', url: 'https://example.com/hook' }],
+    created_at: 0,
+    updated_at: 0,
+    ...overrides,
+  }
+}
+
+function makeDeps(overrides: Partial<CronRunnerDeps> = {}): CronRunnerDeps & {
+  listSpy: ReturnType<typeof vi.fn>
+  findActiveSpy: ReturnType<typeof vi.fn>
+} {
+  const listSpy = vi.fn().mockResolvedValue({ items: [{ id: 'e1', title: 'Hello' }], total: 1 })
+  const findActiveSpy = vi.fn().mockResolvedValue([makeAutomation()])
+
+  return {
+    automationRepository: {
+      findActive: findActiveSpy,
+      list: vi.fn(), findById: vi.fn(), create: vi.fn(),
+      update: vi.fn(), toggle: vi.fn(), delete: vi.fn(),
+    } as unknown as IAutomationRepository,
+    contentRepository: { findMany: listSpy } as unknown as ContentRepository,
+    getSeed: (slug: string) => slug === 'posts' ? SEED : null,
+    env: {},
+    idGenerator: STUB_ID_GENERATOR,
+    listSpy,
+    findActiveSpy,
+    ...overrides,
+  }
+}
+
+describe('runCronAutomations', () => {
+  beforeEach(() => {
+    executeActionMock.mockReset()
+    executeActionMock.mockResolvedValue(undefined)
+  })
+
+  it('calls findActive with ("*", "cron")', async () => {
+    const deps = makeDeps()
+    await runCronAutomations(deps, TICK)
+    expect(deps.findActiveSpy).toHaveBeenCalledWith('*', 'cron')
+  })
+
+  it('batch actions (webhook, send_mail) run once per automation with batch context', async () => {
+    const entries = [{ id: 'e1', title: 'A' }, { id: 'e2', title: 'B' }]
+    const deps = makeDeps()
+    deps.listSpy.mockResolvedValue({ items: entries, total: 2 })
+
+    await runCronAutomations(deps, TICK)
+
+    expect(executeActionMock).toHaveBeenCalledTimes(1)
+    const [, ctx] = executeActionMock.mock.calls[0]
+    // entry is the first entry (for backwards compat); batch count lives in context
+    expect(ctx.entry).toMatchObject({ id: 'e1', title: 'A' })
+    expect(ctx.context).toBeDefined()
+  })
+
+  it('per-entry actions (edit_field, create_entry) run once per matching entry', async () => {
+    const entries = [{ id: 'e1' }, { id: 'e2' }]
+    const deps = makeDeps()
+    deps.findActiveSpy.mockResolvedValue([makeAutomation({ actions: [{ type: 'edit_field', field: 'title', value: 'updated' }] })])
+    deps.listSpy.mockResolvedValue({ items: entries, total: 2 })
+
+    await runCronAutomations(deps, TICK)
+
+    expect(executeActionMock).toHaveBeenCalledTimes(2)
+    expect(executeActionMock.mock.calls[0][1].entry).toMatchObject({ id: 'e1' })
+    expect(executeActionMock.mock.calls[1][1].entry).toMatchObject({ id: 'e2' })
+  })
+
+  it('skips non-matching cron expression, runs matching one', async () => {
+    const matchingAuto = makeAutomation({ id: 'auto_match', triggers: [{ event: 'cron', cron: '* * * * *' }] })
+    const nonMatchingAuto = makeAutomation({ id: 'auto_skip', triggers: [{ event: 'cron', cron: '30 9 * * *' }] })
+    const entries = [{ id: 'e1' }, { id: 'e2' }]
+
+    const deps = makeDeps()
+    deps.findActiveSpy.mockResolvedValue([matchingAuto, nonMatchingAuto])
+    deps.listSpy.mockResolvedValue({ items: entries, total: 2 })
+
+    await runCronAutomations(deps, TICK)
+
+    // webhook = batch, runs once for the matching automation only
+    expect(executeActionMock).toHaveBeenCalledTimes(1)
+  })
+
+  it('passes trigger_conditions as translated filters to repository.findMany', async () => {
+    const auto = makeAutomation({
+      trigger_conditions: {
+        kind: 'group',
+        op: 'AND',
+        children: [
+          { kind: 'predicate', left: { kind: 'ref', key: 'this.title' }, op: 'eq', right: { kind: 'literal', value: 'Hello' } },
+        ],
+      },
+    })
+    const deps = makeDeps()
+    deps.findActiveSpy.mockResolvedValue([auto])
+
+    await runCronAutomations(deps, TICK)
+
+    const call = deps.listSpy.mock.calls[0]
+    const options = call[1]
+    expect(options.filters).toEqual([
+      { column: 'title', type: 'text', conditions: [{ op: 'eq', value: 'Hello' }] },
+    ])
+  })
+
+  it('maps all branch types, system columns, unknown columns, and special operators correctly', async () => {
+    const auto = makeAutomation({
+      trigger_conditions: {
+        kind: 'group',
+        op: 'AND',
+        children: [
+          { kind: 'predicate', left: { kind: 'ref', key: 'this.count' }, op: 'gt', right: { kind: 'literal', value: 5 } },
+          { kind: 'predicate', left: { kind: 'ref', key: 'this.published' }, op: 'eq', right: { kind: 'literal', value: true } },
+          { kind: 'predicate', left: { kind: 'ref', key: 'this.publish_date' }, op: 'isempty' },
+          { kind: 'predicate', left: { kind: 'ref', key: 'this.tags_list' }, op: 'isnotempty' },
+          { kind: 'predicate', left: { kind: 'ref', key: 'this.meta_json' }, op: 'eq', right: { kind: 'literal', value: '{}' } },
+          { kind: 'predicate', left: { kind: 'ref', key: 'this.body_rich' }, op: 'contains', right: { kind: 'literal', value: 'hello' } },
+          { kind: 'predicate', left: { kind: 'ref', key: 'this.status' }, op: 'eq', right: { kind: 'literal', value: 'draft' } },
+          { kind: 'predicate', left: { kind: 'ref', key: 'this.unknown_custom' }, op: 'eq', right: { kind: 'literal', value: 'test' } },
+        ],
+      },
+    })
+    const deps = makeDeps()
+    deps.findActiveSpy.mockResolvedValue([auto])
+
+    await runCronAutomations(deps, TICK)
+
+    const call = deps.listSpy.mock.calls[0]
+    expect(call[1].filters).toEqual([
+      { column: 'count', type: 'number', conditions: [{ op: 'gt', value: 5 }] },
+      { column: 'published', type: 'boolean', conditions: [{ op: 'eq', value: true }] },
+      { column: 'publish_date', type: 'date', conditions: [{ op: 'is_empty', value: null }] },
+      { column: 'tags_list', type: 'tags', conditions: [{ op: 'is_not_empty', value: null }] },
+      { column: 'meta_json', type: 'json', conditions: [{ op: 'eq', value: '{}' }] },
+      { column: 'body_rich', type: 'text', conditions: [{ op: 'contains', value: 'hello' }] },
+      { column: 'status', type: 'system', conditions: [{ op: 'eq', value: 'draft' }] },
+      { column: 'unknown_custom', type: 'text', conditions: [{ op: 'eq', value: 'test' }] },
+    ])
+  })
+
+  it('logs warning and skips when getSeed returns null', async () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const auto = makeAutomation({ seed_slug: 'unknown' })
+    const deps = makeDeps()
+    deps.findActiveSpy.mockResolvedValue([auto])
+
+    await runCronAutomations(deps, TICK)
+
+    expect(executeActionMock).not.toHaveBeenCalled()
+    expect(warnSpy).toHaveBeenCalledWith('[cron] unknown seed', expect.anything())
+    warnSpy.mockRestore()
+  })
+
+  it('continues processing remaining per-entry actions when one entry throws', async () => {
+    const entries = [{ id: 'e1' }, { id: 'e2' }, { id: 'e3' }]
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const deps = makeDeps()
+    deps.findActiveSpy.mockResolvedValue([makeAutomation({ actions: [{ type: 'edit_field', field: 'title', value: 'x' }] })])
+    deps.listSpy.mockResolvedValue({ items: entries, total: 3 })
+    executeActionMock
+      .mockResolvedValueOnce(undefined)
+      .mockRejectedValueOnce(new Error('boom'))
+      .mockResolvedValueOnce(undefined)
+
+    await runCronAutomations(deps, TICK)
+
+    expect(executeActionMock).toHaveBeenCalledTimes(3)
+    expect(errorSpy).toHaveBeenCalledWith('[cron] entry action failed', expect.anything())
+    errorSpy.mockRestore()
+  })
+
+  it('logs and continues to next automation when repository.findMany throws', async () => {
+    const auto1 = makeAutomation({ id: 'auto_01' })
+    const auto2 = makeAutomation({ id: 'auto_02' })
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const deps = makeDeps()
+    deps.findActiveSpy.mockResolvedValue([auto1, auto2])
+    deps.listSpy
+      .mockRejectedValueOnce(new Error('db error'))
+      .mockResolvedValueOnce({ items: [{ id: 'e1' }], total: 1 })
+
+    await runCronAutomations(deps, TICK)
+
+    expect(errorSpy).toHaveBeenCalledWith('[cron] fetch entries failed', expect.anything())
+    // auto2 still processed (webhook = batch, 1 call)
+    expect(executeActionMock).toHaveBeenCalledTimes(1)
+    errorSpy.mockRestore()
+  })
+
+  it('logs error and returns gracefully when findActive throws', async () => {
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const deps = makeDeps()
+    deps.findActiveSpy.mockRejectedValueOnce(new Error('no such table'))
+
+    await expect(runCronAutomations(deps, TICK)).resolves.toBeUndefined()
+    expect(errorSpy).toHaveBeenCalledWith(
+      expect.stringContaining('[cron] Failed to fetch automations'),
+      expect.anything(),
+    )
+    expect(executeActionMock).not.toHaveBeenCalled()
+    errorSpy.mockRestore()
+  })
+
+  it('resolves quietly with zero calls when no active automations exist', async () => {
+    const deps = makeDeps()
+    deps.findActiveSpy.mockResolvedValue([])
+
+    await expect(runCronAutomations(deps, TICK)).resolves.toBeUndefined()
+    expect(executeActionMock).not.toHaveBeenCalled()
+  })
+
+  it('skips automation silently when entries list is empty', async () => {
+    const deps = makeDeps()
+    deps.listSpy.mockResolvedValue({ items: [], total: 0 })
+
+    await runCronAutomations(deps, TICK)
+
+    expect(executeActionMock).not.toHaveBeenCalled()
+  })
+})

package/src/features/automations/__tests__/cron-runner.utils.test.ts

@@ -0,0 +1,140 @@
+import { describe, it, expect } from 'vitest'
+import { cronMatches } from '../cron-runner.utils'
+
+const ts = (iso: string) => new Date(iso).getTime()
+
+describe('cronMatches', () => {
+  it('matches any timestamp with * * * * *', () => {
+    expect(cronMatches('* * * * *', ts('2026-05-14T09:37:00Z'))).toBe(true)
+  })
+
+  it('returns false for null', () => {
+    expect(cronMatches(null, ts('2026-05-14T09:00:00Z'))).toBe(false)
+  })
+
+  it('returns false for empty string', () => {
+    expect(cronMatches('', ts('2026-05-14T09:00:00Z'))).toBe(false)
+  })
+
+  it('returns false for malformed (not 5 fields)', () => {
+    expect(cronMatches('* * * *', ts('2026-05-14T09:00:00Z'))).toBe(false)
+    expect(cronMatches('* * * * * *', ts('2026-05-14T09:00:00Z'))).toBe(false)
+  })
+
+  describe('exact match', () => {
+    it('matches 0 9 * * * at 09:00', () => {
+      expect(cronMatches('0 9 * * *', ts('2026-05-14T09:00:00Z'))).toBe(true)
+    })
+
+    it('does not match 0 9 * * * at 09:01', () => {
+      expect(cronMatches('0 9 * * *', ts('2026-05-14T09:01:00Z'))).toBe(false)
+    })
+  })
+
+  describe('day-of-week', () => {
+    // 2026-05-11 is a Monday (day 1)
+    it('matches 0 9 * * 1 on Monday', () => {
+      expect(cronMatches('0 9 * * 1', ts('2026-05-11T09:00:00Z'))).toBe(true)
+    })
+
+    it('does not match 0 9 * * 1 on Tuesday', () => {
+      expect(cronMatches('0 9 * * 1', ts('2026-05-12T09:00:00Z'))).toBe(false)
+    })
+  })
+
+  describe('list', () => {
+    it('matches 0 9,17 * * * at 09:00', () => {
+      expect(cronMatches('0 9,17 * * *', ts('2026-05-14T09:00:00Z'))).toBe(true)
+    })
+
+    it('matches 0 9,17 * * * at 17:00', () => {
+      expect(cronMatches('0 9,17 * * *', ts('2026-05-14T17:00:00Z'))).toBe(true)
+    })
+
+    it('does not match 0 9,17 * * * at 10:00', () => {
+      expect(cronMatches('0 9,17 * * *', ts('2026-05-14T10:00:00Z'))).toBe(false)
+    })
+  })
+
+  describe('range', () => {
+    it('matches 0 9-11 * * * at 09:00', () => {
+      expect(cronMatches('0 9-11 * * *', ts('2026-05-14T09:00:00Z'))).toBe(true)
+    })
+
+    it('matches 0 9-11 * * * at 10:00', () => {
+      expect(cronMatches('0 9-11 * * *', ts('2026-05-14T10:00:00Z'))).toBe(true)
+    })
+
+    it('matches 0 9-11 * * * at 11:00', () => {
+      expect(cronMatches('0 9-11 * * *', ts('2026-05-14T11:00:00Z'))).toBe(true)
+    })
+
+    it('does not match 0 9-11 * * * at 12:00', () => {
+      expect(cronMatches('0 9-11 * * *', ts('2026-05-14T12:00:00Z'))).toBe(false)
+    })
+  })
+
+  describe('step', () => {
+    it('matches */15 * * * * at :00', () => {
+      expect(cronMatches('*/15 * * * *', ts('2026-05-14T09:00:00Z'))).toBe(true)
+    })
+
+    it('matches */15 * * * * at :15', () => {
+      expect(cronMatches('*/15 * * * *', ts('2026-05-14T09:15:00Z'))).toBe(true)
+    })
+
+    it('matches */15 * * * * at :30', () => {
+      expect(cronMatches('*/15 * * * *', ts('2026-05-14T09:30:00Z'))).toBe(true)
+    })
+
+    it('matches */15 * * * * at :45', () => {
+      expect(cronMatches('*/15 * * * *', ts('2026-05-14T09:45:00Z'))).toBe(true)
+    })
+
+    it('does not match */15 * * * * at :07', () => {
+      expect(cronMatches('*/15 * * * *', ts('2026-05-14T09:07:00Z'))).toBe(false)
+    })
+  })
+
+  describe('range + step', () => {
+    it('matches 5-30/5 * * * * at :05', () => {
+      expect(cronMatches('5-30/5 * * * *', ts('2026-05-14T09:05:00Z'))).toBe(true)
+    })
+
+    it('matches 5-30/5 * * * * at :10', () => {
+      expect(cronMatches('5-30/5 * * * *', ts('2026-05-14T09:10:00Z'))).toBe(true)
+    })
+
+    it('matches 5-30/5 * * * * at :30', () => {
+      expect(cronMatches('5-30/5 * * * *', ts('2026-05-14T09:30:00Z'))).toBe(true)
+    })
+
+    it('does not match 5-30/5 * * * * at :00', () => {
+      expect(cronMatches('5-30/5 * * * *', ts('2026-05-14T09:00:00Z'))).toBe(false)
+    })
+
+    it('does not match 5-30/5 * * * * at :35', () => {
+      expect(cronMatches('5-30/5 * * * *', ts('2026-05-14T09:35:00Z'))).toBe(false)
+    })
+  })
+
+  describe('edge cases and malformed field expressions', () => {
+    it('returns false for non-finite or zero step', () => {
+      expect(cronMatches('*/0 * * * *', ts('2026-05-14T09:00:00Z'))).toBe(false)
+      expect(cronMatches('*/abc * * * *', ts('2026-05-14T09:00:00Z'))).toBe(false)
+      expect(cronMatches('*/-5 * * * *', ts('2026-05-14T09:00:00Z'))).toBe(false)
+    })
+
+    it('returns false when step is applied to a single value instead of range or wildcard', () => {
+      expect(cronMatches('5/2 * * * *', ts('2026-05-14T09:05:00Z'))).toBe(false)
+    })
+
+    it('returns false for malformed range bounds', () => {
+      expect(cronMatches('abc-def * * * *', ts('2026-05-14T09:00:00Z'))).toBe(false)
+    })
+
+    it('returns false for invalid single numeric field', () => {
+      expect(cronMatches('abc * * * *', ts('2026-05-14T09:00:00Z'))).toBe(false)
+    })
+  })
+})