@ossy/platform 3.2.0 → 3.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossy/platform",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "Ossy application server runtime",
   "repository": {
     "type": "git",
@@ -51,7 +51,7 @@
     "@ossy/observability": "^3.0.9",
     "@ossy/policies": "^3.0.9",
     "@ossy/schema": "^3.0.9",
-    "@ossy/sdk": "^3.2.0",
+    "@ossy/sdk": "^3.3.0",
     "@ossy/tokens": "^3.0.9",
     "@ossy/users": "^3.2.0",
     "@ossy/workspaces": "^3.2.0",
@@ -74,5 +74,5 @@
     "src",
     "Dockerfile"
   ],
-  "gitHead": "b045f1fd7f2fe00c776b9ea96f76083b93fd8556"
+  "gitHead": "19e8bae4c1e9df79270218f28c0c9391f4f9871c"
 }

package/src/test/flow-click.js

@@ -0,0 +1,43 @@
+/**
+ * Normalize a declarative flow `click` step into a Playwright locator click.
+ * Prefer `{ action }` for `data-action` controls; use `click` for structural hooks
+ * (e.g. overlay backdrop) that are not action POJOs.
+ *
+ * @param {unknown} click
+ * @returns {{ selector: string, position?: { x: number, y: number } }}
+ */
+export function resolveClickTarget (click) {
+  if (typeof click === 'string') {
+    const selector = click.trim()
+    if (!selector) {
+      throw new Error('click step requires a non-empty CSS selector')
+    }
+    return { selector }
+  }
+
+  if (click != null && typeof click === 'object' && !Array.isArray(click)) {
+    const selector = typeof click.selector === 'string' ? click.selector.trim() : ''
+    if (!selector) {
+      throw new Error('click step requires a non-empty CSS selector')
+    }
+
+    const out = { selector }
+    if (click.position != null) {
+      if (
+        typeof click.position !== 'object'
+        || Array.isArray(click.position)
+        || !Number.isFinite(Number(click.position.x))
+        || !Number.isFinite(Number(click.position.y))
+      ) {
+        throw new Error('click.position requires { x, y } with finite numbers')
+      }
+      out.position = {
+        x: Number(click.position.x),
+        y: Number(click.position.y),
+      }
+    }
+    return out
+  }
+
+  throw new Error('click step requires a non-empty CSS selector')
+}

package/src/test/flow-click.spec.js

@@ -0,0 +1,42 @@
+import { describe, expect, it } from '@jest/globals'
+import { resolveClickTarget } from './flow-click.js'
+
+describe('resolveClickTarget', () => {
+  it('accepts a bare selector string', () => {
+    expect(resolveClickTarget('[data-overlay]')).toEqual({
+      selector: '[data-overlay]',
+    })
+  })
+
+  it('accepts { selector } and trims whitespace', () => {
+    expect(resolveClickTarget({ selector: ' [data-ossy-mobile-shell-nav-overlay] ' })).toEqual({
+      selector: '[data-ossy-mobile-shell-nav-overlay]',
+    })
+  })
+
+  it('accepts optional { position: { x, y } }', () => {
+    expect(resolveClickTarget({
+      selector: '[data-ossy-mobile-shell-nav-overlay]',
+      position: { x: 360, y: 200 },
+    })).toEqual({
+      selector: '[data-ossy-mobile-shell-nav-overlay]',
+      position: { x: 360, y: 200 },
+    })
+  })
+
+  it('rejects empty or invalid values', () => {
+    expect(() => resolveClickTarget('')).toThrow(/non-empty CSS selector/)
+    expect(() => resolveClickTarget('   ')).toThrow(/non-empty CSS selector/)
+    expect(() => resolveClickTarget(null)).toThrow(/non-empty CSS selector/)
+    expect(() => resolveClickTarget({ selector: '' })).toThrow(/non-empty CSS selector/)
+    expect(() => resolveClickTarget([])).toThrow(/non-empty CSS selector/)
+    expect(() => resolveClickTarget({
+      selector: '[data-overlay]',
+      position: { x: 'left' },
+    })).toThrow(/position requires/)
+    expect(() => resolveClickTarget({
+      selector: '[data-overlay]',
+      position: 10,
+    })).toThrow(/position requires/)
+  })
+})

package/src/test/flow-press.js

@@ -0,0 +1,25 @@
+/**
+ * Normalize a declarative flow `press` step into a Playwright keyboard key.
+ *
+ * @param {unknown} press
+ * @returns {string}
+ */
+export function resolvePressKey (press) {
+  if (typeof press === 'string') {
+    const key = press.trim()
+    if (!key) {
+      throw new Error('press step requires a non-empty key string (e.g. "Escape")')
+    }
+    return key
+  }
+
+  if (press != null && typeof press === 'object' && !Array.isArray(press)) {
+    const key = typeof press.key === 'string' ? press.key.trim() : ''
+    if (!key) {
+      throw new Error('press step requires a non-empty key string (e.g. "Escape")')
+    }
+    return key
+  }
+
+  throw new Error('press step requires a non-empty key string (e.g. "Escape")')
+}

package/src/test/flow-press.spec.js

@@ -0,0 +1,25 @@
+import { describe, expect, it } from '@jest/globals'
+import { resolvePressKey } from './flow-press.js'
+
+describe('resolvePressKey', () => {
+  it('accepts a bare key string', () => {
+    expect(resolvePressKey('Escape')).toBe('Escape')
+    expect(resolvePressKey('Enter')).toBe('Enter')
+    expect(resolvePressKey('Tab')).toBe('Tab')
+    expect(resolvePressKey('Shift+Tab')).toBe('Shift+Tab')
+  })
+
+  it('accepts { key } and trims whitespace', () => {
+    expect(resolvePressKey({ key: ' Escape ' })).toBe('Escape')
+    expect(resolvePressKey({ key: ' Shift+Tab ' })).toBe('Shift+Tab')
+  })
+
+  it('rejects empty or invalid values', () => {
+    expect(() => resolvePressKey('')).toThrow(/non-empty key/)
+    expect(() => resolvePressKey('   ')).toThrow(/non-empty key/)
+    expect(() => resolvePressKey(null)).toThrow(/non-empty key/)
+    expect(() => resolvePressKey({ key: '' })).toThrow(/non-empty key/)
+    expect(() => resolvePressKey({ key: 27 })).toThrow(/non-empty key/)
+    expect(() => resolvePressKey([])).toThrow(/non-empty key/)
+  })
+})

package/src/test/flow-runner.js

@@ -19,12 +19,18 @@ import {
   interpolateContextString,
   resolveContextValue,
 } from './flow-context.js'
+import { resolveClickTarget } from './flow-click.js'
+import { resolvePressKey } from './flow-press.js'
+import { resolveViewportSize } from './flow-viewport.js'
 
 export {
   escapeCssAttrValue,
   interpolateContextString,
   resolveContextValue,
 } from './flow-context.js'
+export { resolveClickTarget } from './flow-click.js'
+export { resolvePressKey } from './flow-press.js'
+export { resolveViewportSize } from './flow-viewport.js'
 
 const FLOW_PATTERN = /\.flow\.(mjs|cjs|js)$/
 
@@ -201,6 +207,31 @@ export async function runFlow (flow, options = {}) {
       continue
     }
 
+    if (step.viewport != null) {
+      if (!page) throw new Error('viewport step requires a Playwright page')
+      await page.setViewportSize(resolveViewportSize(step.viewport))
+      continue
+    }
+
+    if (step.press != null) {
+      if (!page) throw new Error('press step requires a Playwright page')
+      await page.keyboard.press(resolvePressKey(step.press))
+      continue
+    }
+
+    if (step.click != null) {
+      if (!page) throw new Error('click step requires a Playwright page')
+      const { selector, position } = resolveClickTarget(step.click)
+      const resolvedSelector = interpolateContextString(selector, context, {
+        escape: escapeCssAttrValue,
+      })
+      const locator = page.locator(resolvedSelector).first()
+      const clickTimeout = step.timeout ?? 15000
+      await locator.waitFor({ state: 'visible', timeout: clickTimeout })
+      await locator.click(position ? { position } : undefined)
+      continue
+    }
+
     if (step.form) {
       if (!page) throw new Error('form step requires a Playwright page')
       const formMeta = step.form
@@ -309,19 +340,37 @@ export async function runFlow (flow, options = {}) {
 
     if (step.result) {
       if (!page) throw new Error('result step requires a Playwright page')
-      const { text, url, page: pageRef, action, selector, timeout = 8000 } = step.result
+      const {
+        text,
+        url,
+        page: pageRef,
+        action,
+        selector,
+        hidden = false,
+        timeout = 8000,
+      } = step.result
+      const assertLocator = async (locator) => {
+        if (hidden) {
+          await expectFn(locator).toBeHidden({ timeout })
+          return
+        }
+        await expectFn(locator).toBeVisible({ timeout })
+      }
       if (action != null) {
         const actionId = resolveActionId(action)
         const service = resolveActionService(action, step.result.service)
-        await expectFn(page.locator(actionSelector(actionId, service)).first()).toBeVisible({ timeout })
+        await assertLocator(page.locator(actionSelector(actionId, service)).first())
       }
       if (selector != null) {
         const resolvedSelector = interpolateContextString(selector, context, {
           escape: escapeCssAttrValue,
         })
-        await expectFn(page.locator(resolvedSelector).first()).toBeVisible({ timeout })
+        await assertLocator(page.locator(resolvedSelector).first())
       }
       if (text != null) {
+        if (hidden) {
+          throw new Error('result.text cannot use hidden: true — assert via action or selector')
+        }
         const pattern = text instanceof RegExp ? text : new RegExp(text, 'i')
         await expectFn(page.getByText(pattern).first()).toBeVisible({ timeout })
       }

package/src/test/flow-viewport.js

@@ -0,0 +1,23 @@
+/**
+ * Normalize a declarative flow `viewport` step into Playwright setViewportSize input.
+ *
+ * @param {unknown} viewport
+ * @returns {{ width: number, height: number }}
+ */
+export function resolveViewportSize (viewport) {
+  if (viewport == null || typeof viewport !== 'object' || Array.isArray(viewport)) {
+    throw new Error('viewport step requires { width, height } with positive numbers')
+  }
+
+  const width = Number(viewport.width)
+  const height = Number(viewport.height)
+
+  if (!Number.isFinite(width) || width <= 0 || !Number.isFinite(height) || height <= 0) {
+    throw new Error('viewport step requires { width, height } with positive numbers')
+  }
+
+  return {
+    width: Math.round(width),
+    height: Math.round(height),
+  }
+}

package/src/test/flow-viewport.spec.js

@@ -0,0 +1,26 @@
+import { describe, expect, it } from '@jest/globals'
+import { resolveViewportSize } from './flow-viewport.js'
+
+describe('resolveViewportSize', () => {
+  it('accepts positive width/height', () => {
+    expect(resolveViewportSize({ width: 390, height: 844 })).toEqual({
+      width: 390,
+      height: 844,
+    })
+  })
+
+  it('rounds fractional dimensions', () => {
+    expect(resolveViewportSize({ width: 389.6, height: 843.2 })).toEqual({
+      width: 390,
+      height: 843,
+    })
+  })
+
+  it('rejects missing or non-positive sizes', () => {
+    expect(() => resolveViewportSize(null)).toThrow(/width, height/)
+    expect(() => resolveViewportSize({ width: 390 })).toThrow(/width, height/)
+    expect(() => resolveViewportSize({ width: 0, height: 844 })).toThrow(/width, height/)
+    expect(() => resolveViewportSize({ width: -1, height: 844 })).toThrow(/width, height/)
+    expect(() => resolveViewportSize('mobile')).toThrow(/width, height/)
+  })
+})