@lowdefy/shell 3.23.2 → 7.2.0

package/src/dev/steps/createStepRunner.js

@@ -0,0 +1,184 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { get, type } from '@lowdefy/helpers';
+
+import findBlock from './findBlock.js';
+import findPageContext from '../tab/findPageContext.js';
+import getShownPage from '../tab/getShownPage.js';
+import waitForSettle from './waitForSettle.js';
+import waitUntil, { sleep } from './waitUntil.js';
+
+const STEPS = ['click', 'fill', 'select', 'press', 'wait', 'screenshot'];
+const SETTLE_MS = 5000;
+
+function readOptionLabel(option) {
+  if (type.isObject(option)) {
+    return String(option.label ?? option.value);
+  }
+  return String(option);
+}
+
+function readOptionValue(option) {
+  return type.isObject(option) ? option.value : option;
+}
+
+/**
+ * Runs the browser's journey steps on the shell, by block id: the dev-tab client's answer to a
+ * step-request. A step acts through the engine, as the block's own view does when it is pressed
+ * or typed in, and waits for the action chain it started to finish:
+ * - `{ click: target }`: the block's onClick.
+ * - `{ fill: { blockId, value } }`: sets the input's value, then its onChange.
+ * - `{ select: { blockId, value } }`: the option whose label (or value) is `value`.
+ * - `{ press: 'Enter' }`: the onPressEnter of the input filled last.
+ * - `{ wait: { ms } | { request } | { state } }`.
+ * - `{ screenshot: name? }`: the root view as a base64 PNG.
+ * Resolves `{ ok: true, settled }` (and `image` for a screenshot); throws when the step cannot run.
+ *
+ * @param {Object} params
+ * @param {() => Promise<string>} params.capture Captures the root view as a base64 PNG.
+ * @param {() => Object} params.getLowdefy The open app's lowdefy object.
+ * @param {number} [params.timeout] How long a step waits for its block or condition, in ms.
+ */
+function createStepRunner({ capture, getLowdefy, timeout = 5000 }) {
+  let lastInputBlockId = null;
+
+  async function settle(lowdefy) {
+    const settled = await waitForSettle({ lowdefy, timeout: SETTLE_MS });
+    return { ok: true, settled };
+  }
+
+  async function click({ lowdefy, target }) {
+    const { block } = await findBlock({ lowdefy, target, timeout });
+    if (block.eval.properties?.disabled === true) {
+      throw new Error(`Block "${block.blockId}" is disabled.`);
+    }
+    await block.triggerEvent({ name: 'onClick' });
+    return settle(lowdefy);
+  }
+
+  async function findInput({ lowdefy, target }) {
+    const found = await findBlock({ lowdefy, target, timeout });
+    if (!type.isFunction(found.block.setValue)) {
+      throw new Error(`Block "${found.block.blockId}" is not an input.`);
+    }
+    return found.block;
+  }
+
+  async function setInputValue({ block, lowdefy, value }) {
+    block.setValue(value);
+    lastInputBlockId = block.blockId;
+    await block.triggerEvent({ name: 'onChange' });
+    return settle(lowdefy);
+  }
+
+  async function fill({ lowdefy, target }) {
+    if (!type.isObject(target) || !Object.hasOwn(target, 'value')) {
+      throw new Error(`A fill step needs { blockId, value }. Received ${JSON.stringify(target)}.`);
+    }
+    const block = await findInput({ lowdefy, target });
+    return setInputValue({ block, lowdefy, value: target.value });
+  }
+
+  async function select({ lowdefy, target }) {
+    if (!type.isObject(target) || !Object.hasOwn(target, 'value')) {
+      throw new Error(
+        `A select step needs { blockId, value }. Received ${JSON.stringify(target)}.`
+      );
+    }
+    const block = await findInput({ lowdefy, target });
+    const options = block.eval.properties?.options ?? [];
+    const option = options.find((item) => readOptionLabel(item) === String(target.value));
+    if (option === undefined) {
+      throw new Error(
+        `Block "${block.blockId}" has no option "${target.value}". Its options are ${JSON.stringify(
+          options.map(readOptionLabel)
+        )}.`
+      );
+    }
+    return setInputValue({ block, lowdefy, value: readOptionValue(option) });
+  }
+
+  async function press({ key, lowdefy }) {
+    if (key !== 'Enter') {
+      throw new Error(`A phone presses only "Enter". Received ${JSON.stringify(key)}.`);
+    }
+    if (lastInputBlockId === null) {
+      throw new Error('Press "Enter" needs an input filled before it.');
+    }
+    const { block } = await findBlock({ lowdefy, target: lastInputBlockId, timeout });
+    await block.triggerEvent({ name: 'onPressEnter' });
+    return settle(lowdefy);
+  }
+
+  async function waitFor({ lowdefy, until }) {
+    if (type.isObject(until) && type.isNumber(until.ms)) {
+      await sleep(until.ms);
+      return { ok: true };
+    }
+    if (!type.isObject(until) || !(type.isString(until.request) || type.isString(until.state))) {
+      throw new Error(
+        `A wait step needs { ms }, { request } or { state }. Received ${JSON.stringify(until)}.`
+      );
+    }
+    const done = await waitUntil({
+      timeout,
+      check: () => {
+        const { context } = findPageContext({ lowdefy, page: getShownPage(lowdefy) });
+        if (context === undefined) return undefined;
+        if (type.isString(until.request)) {
+          const call = context.requests?.[until.request]?.[0];
+          return call !== undefined && call.loading !== true ? true : undefined;
+        }
+        return get(context.state, until.state) !== undefined ? true : undefined;
+      },
+    });
+    if (done === undefined) {
+      throw new Error(`Waited ${timeout} ms for ${JSON.stringify(until)}.`);
+    }
+    return { ok: true };
+  }
+
+  async function run({ step }) {
+    if (!type.isObject(step) || Object.keys(step).length !== 1) {
+      throw new Error(`A step is an object with one key. Received ${JSON.stringify(step)}.`);
+    }
+    const [name] = Object.keys(step);
+    const lowdefy = getLowdefy();
+    switch (name) {
+      case 'click':
+        return click({ lowdefy, target: step.click });
+      case 'fill':
+        return fill({ lowdefy, target: step.fill });
+      case 'select':
+        return select({ lowdefy, target: step.select });
+      case 'press':
+        return press({ key: step.press, lowdefy });
+      case 'wait':
+        return waitFor({ lowdefy, until: step.wait });
+      case 'screenshot':
+        return { ok: true, name: step.screenshot ?? null, image: await capture() };
+      default:
+        throw new Error(
+          `A phone runs the steps ${STEPS.join(', ')}. Received ${JSON.stringify(name)}.`
+        );
+    }
+  }
+
+  return { run };
+}
+
+export default createStepRunner;

package/src/dev/steps/createStepRunner.test.js

@@ -0,0 +1,262 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import React from 'react';
+import { jest } from '@jest/globals';
+import { Pressable, Text, View } from 'react-native';
+import { act, fireEvent, render, screen } from '@testing-library/react-native';
+import { createNativeGlobals, LowdefyPage } from '@lowdefy/client-native';
+import { SetState } from '@lowdefy/actions-core/actions';
+import { _state } from '@lowdefy/operators-js/operators/client';
+
+import createMemoryStore from '../../host/createMemoryStore.js';
+import createStepRunner from './createStepRunner.js';
+
+// Stand-ins for native blocks: a container, a button, a text input and a selector.
+function Box({ content }) {
+  return <View>{content.content?.()}</View>;
+}
+Box.meta = { category: 'container', slots: { content: 'Child blocks.' } };
+
+function Button({ methods, properties }) {
+  return (
+    <Pressable accessibilityRole="button" onPress={() => methods.triggerEvent({ name: 'onClick' })}>
+      <Text>{properties.title}</Text>
+    </Pressable>
+  );
+}
+Button.meta = { category: 'display' };
+
+function TextInput({ blockId, value }) {
+  return <Text testID={`${blockId}-value`}>{value ?? ''}</Text>;
+}
+TextInput.meta = { category: 'input', valueType: 'string' };
+
+function Selector({ blockId, value }) {
+  return <Text testID={`${blockId}-value`}>{JSON.stringify(value ?? null)}</Text>;
+}
+Selector.meta = { category: 'input', valueType: 'any' };
+
+// An action that takes a while, so a step that returns before its chain ends would be seen.
+function Pause({ params }) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, params.ms);
+  });
+}
+
+const types = {
+  actions: { Pause, SetState },
+  blocks: { Box, Button, Selector, TextInput },
+  operators: { _state },
+};
+
+function block({ id, type, events, ...rest }) {
+  const built = { id: `block:form:${id}:0`, blockId: id, type, ...rest };
+  if (events) {
+    built.events = Object.fromEntries(
+      Object.entries(events).map(([name, actions]) => [name, { try: actions, catch: [] }])
+    );
+  }
+  return built;
+}
+
+const pageConfig = {
+  id: 'page:form',
+  pageId: 'form',
+  blockId: 'form',
+  type: 'Box',
+  path: 'form',
+  linkPaths: {},
+  subscriptions: [],
+  requests: [],
+  slots: {
+    content: {
+      blocks: [
+        block({
+          id: 'title',
+          type: 'TextInput',
+          events: {
+            onChange: [{ id: 'echo', type: 'SetState', params: { echo: { _state: 'title' } } }],
+            onPressEnter: [{ id: 'enter', type: 'SetState', params: { entered: true } }],
+          },
+        }),
+        block({
+          id: 'priority',
+          type: 'Selector',
+          properties: {
+            options: [
+              { label: 'Low', value: 'low' },
+              { label: 'High', value: 'high' },
+            ],
+          },
+        }),
+        block({
+          id: 'save',
+          type: 'Button',
+          properties: { title: 'Save' },
+          events: {
+            onClick: [
+              { id: 'pause', type: 'Pause', params: { ms: 200 } },
+              { id: 'saved', type: 'SetState', params: { saved: true } },
+            ],
+          },
+        }),
+        block({ id: 'locked', type: 'Button', properties: { title: 'Locked', disabled: true } }),
+        block({ id: 'hidden', type: 'Button', visible: false, properties: { title: 'Hidden' } }),
+      ],
+    },
+  },
+};
+
+const rootConfig = {
+  classMap: {},
+  home: { configured: true, pageId: 'form' },
+  lowdefyApp: { slug: 'test-app' },
+  menus: [],
+  pagePaths: { form: 'form' },
+  theme: { light: {}, dark: {} },
+};
+
+async function renderForm() {
+  const fetch = jest.fn();
+  const host = {
+    fetch,
+    globals: createNativeGlobals({
+      assign: jest.fn(),
+      fetch,
+      getPath: () => '/form',
+      origin: 'https://app.lowdefy.test',
+    }),
+    onBuildChanged: jest.fn(),
+    onCallerChanged: jest.fn(),
+    router: { back: jest.fn(), push: jest.fn(), replace: jest.fn() },
+    sessionStorage: createMemoryStore(),
+    storage: createMemoryStore(),
+    WebSocket: jest.fn(),
+    websocketUrl: (apiPath) => apiPath,
+  };
+  const lowdefy = {};
+  const core = {
+    apiBase: 'https://app.lowdefy.test',
+    auth: { authConfig: {} },
+    basePath: '',
+    lowdefy,
+  };
+  await render(
+    <LowdefyPage
+      core={core}
+      host={host}
+      pageConfig={pageConfig}
+      rootConfig={rootConfig}
+      types={types}
+    />
+  );
+  await screen.findByText('Save');
+  const capture = jest.fn(async () => 'iVBORw0KGgo=');
+  const runner = createStepRunner({ capture, getLowdefy: () => lowdefy, timeout: 300 });
+  const state = () => lowdefy.contexts['page:form'].state;
+  async function run(step) {
+    let result;
+    await act(async () => {
+      result = await runner.run({ step });
+    });
+    return result;
+  }
+  async function fail(step) {
+    let error;
+    await act(async () => {
+      error = await runner.run({ step }).catch((caught) => caught);
+    });
+    return error.message;
+  }
+  return { capture, fail, run, state };
+}
+
+test('a click step finds the block by the id its view carries as testID and waits for its action chain', async () => {
+  const { run, state } = await renderForm();
+  expect(screen.getByTestId('save')).toBeTruthy();
+  const result = await run({ click: 'save' });
+  expect(result).toEqual({ ok: true, settled: true });
+  expect(state().saved).toBe(true);
+});
+
+test('a click step takes a { blockId } target', async () => {
+  const { run, state } = await renderForm();
+  await run({ click: { blockId: 'save' } });
+  expect(state().saved).toBe(true);
+});
+
+test('a fill step sets an input and runs its onChange, which the page then shows', async () => {
+  const { run, state } = await renderForm();
+  await run({ fill: { blockId: 'title', value: 'Quarterly' } });
+  expect(state().title).toBe('Quarterly');
+  expect(state().echo).toBe('Quarterly');
+  expect(screen.getByTestId('title-value').props.children).toBe('Quarterly');
+});
+
+test('a press Enter step runs the onPressEnter of the input filled last', async () => {
+  const { run, state } = await renderForm();
+  await run({ fill: { blockId: 'title', value: 'Quarterly' } });
+  await run({ press: 'Enter' });
+  expect(state().entered).toBe(true);
+});
+
+test('a select step picks the option by its label', async () => {
+  const { run, state } = await renderForm();
+  await run({ select: { blockId: 'priority', value: 'High' } });
+  expect(state().priority).toBe('high');
+});
+
+test('a wait step waits for state to be set', async () => {
+  const { run, state } = await renderForm();
+  await act(async () => {
+    fireEvent.press(screen.getByText('Save'));
+  });
+  expect(state().saved).toBeUndefined();
+  expect(await run({ wait: { state: 'saved' } })).toEqual({ ok: true });
+  expect(state().saved).toBe(true);
+});
+
+test('a screenshot step captures the root view', async () => {
+  const { capture, run } = await renderForm();
+  expect(await run({ screenshot: 'after-save' })).toEqual({
+    ok: true,
+    name: 'after-save',
+    image: 'iVBORw0KGgo=',
+  });
+  expect(capture).toHaveBeenCalledTimes(1);
+});
+
+test('steps that cannot run say why', async () => {
+  const { fail } = await renderForm();
+  expect(await fail({ click: 'missing' })).toBe(
+    'Block "missing" is not on page "form". Waited 300 ms.'
+  );
+  expect(await fail({ click: 'hidden' })).toBe('Block "hidden" is not visible. Waited 300 ms.');
+  expect(await fail({ click: 'locked' })).toBe('Block "locked" is disabled.');
+  expect(await fail({ fill: { blockId: 'save', value: 'x' } })).toBe(
+    'Block "save" is not an input.'
+  );
+  expect(await fail({ select: { blockId: 'priority', value: 'Urgent' } })).toBe(
+    'Block "priority" has no option "Urgent". Its options are ["Low","High"].'
+  );
+  expect(await fail({ press: 'Enter' })).toBe('Press "Enter" needs an input filled before it.');
+  expect(await fail({ press: 'Tab' })).toBe('A phone presses only "Enter". Received "Tab".');
+  expect(await fail({ click: { blockId: 'save', text: 'Save' } })).toMatch(/by blockId only/);
+  expect(await fail({ goto: 'home' })).toBe(
+    'A phone runs the steps click, fill, select, press, wait, screenshot. Received "goto".'
+  );
+});

package/src/dev/steps/findBlock.js

@@ -0,0 +1,78 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { type } from '@lowdefy/helpers';
+
+import findPageContext from '../tab/findPageContext.js';
+import getShownPage from '../tab/getShownPage.js';
+import waitUntil from './waitUntil.js';
+
+// A step's target: a block id, or `{ blockId }`. The browser's grid, text and nth targets read the
+// DOM, which a phone does not have.
+function readBlockId(target) {
+  if (type.isString(target)) {
+    return target;
+  }
+  if (type.isObject(target) && type.isString(target.blockId)) {
+    const others = Object.keys(target).filter((key) => !['blockId', 'value'].includes(key));
+    if (others.length > 0) {
+      throw new Error(
+        `A step on a phone targets a block by blockId only. Received ${JSON.stringify(target)}.`
+      );
+    }
+    return target.blockId;
+  }
+  throw new Error(
+    `A step target must be a blockId or { blockId }. Received ${JSON.stringify(target)}.`
+  );
+}
+
+/**
+ * The block a step acts on, on the page the shell shows: `{ block, context, page }`. Its view is
+ * the one with the block id as testID (client-native BlockLayout), so a step needs no screen
+ * position. Waits up to `timeout` ms for the page to render the block and show it.
+ */
+async function findBlock({ lowdefy, target, timeout }) {
+  const blockId = readBlockId(target);
+  let lastError = null;
+  const found = await waitUntil({
+    timeout,
+    check: () => {
+      const page = getShownPage(lowdefy);
+      const { context, error } = findPageContext({ lowdefy, page });
+      if (error) {
+        lastError = error;
+        return undefined;
+      }
+      const block = context._internal.RootSlots?.map?.[blockId];
+      if (type.isNone(block)) {
+        lastError = `Block "${blockId}" is not on page "${page.pageId}".`;
+        return undefined;
+      }
+      if (block.eval?.visible === false) {
+        lastError = `Block "${blockId}" is not visible.`;
+        return undefined;
+      }
+      return { block, context, page };
+    },
+  });
+  if (found === undefined) {
+    throw new Error(`${lastError} Waited ${timeout} ms.`);
+  }
+  return found;
+}
+
+export default findBlock;

package/src/dev/steps/isContextSettled.js

@@ -0,0 +1,37 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+// A page context with nothing left running: its onInit and onInitAsync (and the app's) are done, no
+// block event is running (an onClick's action chain, an onMountAsync), no request is loading and
+// every subscription has connected or failed. The dev server's isPageReady reads a browser tab the
+// same way.
+function isContextSettled({ context, lowdefy }) {
+  if (context._internal?.onInitDone !== true) return false;
+  if (context._internal?.onInitAsyncDone !== true) return false;
+  const appContext = lowdefy.appContext;
+  if (appContext && appContext._internal?.onInitAsyncDone !== true) return false;
+  const blocks = Object.values(context._internal?.RootSlots?.map ?? {});
+  const running = blocks.some((block) =>
+    Object.values(block?.Events?.events ?? {}).some((event) => event?.loading === true)
+  );
+  if (running) return false;
+  const requests = Object.values(context.requests ?? {});
+  if (requests.some((calls) => calls?.[0]?.loading)) return false;
+  const channels = Object.values(context.websockets ?? {});
+  return channels.every((channel) => channel?.connected === true || Boolean(channel?.error));
+}
+
+export default isContextSettled;

package/src/dev/steps/waitForSettle.js

@@ -0,0 +1,39 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import findPageContext from '../tab/findPageContext.js';
+import getShownPage from '../tab/getShownPage.js';
+import isContextSettled from './isContextSettled.js';
+import waitUntil from './waitUntil.js';
+
+// Waits, at most `timeout` ms, for the page the shell shows (it may have changed: a click can open
+// another page) to finish what an interaction started. True once settled; false when it is still
+// busy, which, as in the browser runner, does not fail the step.
+async function waitForSettle({ lowdefy, timeout }) {
+  const settled = await waitUntil({
+    timeout,
+    check: () => {
+      const { context } = findPageContext({ lowdefy, page: getShownPage(lowdefy) });
+      if (context === undefined || !isContextSettled({ context, lowdefy })) {
+        return undefined;
+      }
+      return true;
+    },
+  });
+  return settled === true;
+}
+
+export default waitForSettle;

package/src/dev/steps/waitUntil.js

@@ -0,0 +1,40 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+const POLL_MS = 50;
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// Calls check every 50 ms until it returns a value other than undefined, and resolves with it, or
+// with undefined once `timeout` ms have passed.
+async function waitUntil({ check, timeout }) {
+  const deadline = Date.now() + timeout;
+  for (;;) {
+    const value = check();
+    if (value !== undefined) {
+      return value;
+    }
+    if (Date.now() >= deadline) {
+      return undefined;
+    }
+    await sleep(POLL_MS);
+  }
+}
+
+export { sleep };
+export default waitUntil;