@lowdefy/shell 0.0.0-experimental-20261019052246

package/src/dev/recorder/createNativeRecorder.test.js

@@ -0,0 +1,307 @@
+/*
+  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, TextInput as RNTextInput, 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 validateTraceRecord from '@lowdefy/node-utils/journeyTrace/validateTraceRecord.js';
+
+import createMemoryStore from '../../host/createMemoryStore.js';
+import createNativeRecorder from './createNativeRecorder.js';
+
+// The records the dev server's recording validation runs over (server-dev
+// src/routes/devRecording.test.mjs): what this recorder writes for a click, a fill and a select.
+const fixture = require('../../../../servers/server-dev/test/nativeRecordingFixture.json');
+
+// Stand-ins for native blocks that call their methods as blocks-native's do.
+function Box({ content }) {
+  return <View>{content.content?.()}</View>;
+}
+Box.meta = { category: 'container', slots: { content: 'Child blocks.' } };
+
+function Button({ blockId, methods, properties }) {
+  return (
+    <Pressable
+      accessibilityRole="button"
+      onPress={() => methods.triggerEvent({ name: 'onClick' })}
+      testID={`${blockId}-press`}
+    >
+      <Text>{properties.title}</Text>
+    </Pressable>
+  );
+}
+Button.meta = { category: 'display' };
+
+function TextInput({ blockId, methods, properties, value }) {
+  return (
+    <RNTextInput
+      onChangeText={(text) => {
+        methods.setValue(text);
+        methods.triggerEvent({ name: 'onChange', event: { value: text } });
+      }}
+      onSubmitEditing={() => methods.triggerEvent({ name: 'onPressEnter' })}
+      secureTextEntry={properties.type === 'password'}
+      testID={`${blockId}_input`}
+      value={value ?? ''}
+    />
+  );
+}
+TextInput.meta = { category: 'input', valueType: 'string' };
+
+function Selector({ blockId, methods, properties }) {
+  return (
+    <View>
+      {properties.options.map((option) => (
+        <Pressable
+          key={option.value}
+          onPress={() => {
+            methods.setValue(option.value);
+            methods.triggerEvent({ name: 'onChange', event: { value: option.value } });
+          }}
+          testID={`${blockId}-${option.value}`}
+        >
+          <Text>{option.label}</Text>
+        </Pressable>
+      ))}
+    </View>
+  );
+}
+Selector.meta = { category: 'input', valueType: 'any' };
+
+const types = {
+  actions: { SetState },
+  blocks: { Box, Button, Selector, TextInput },
+  operators: { _state },
+};
+
+function block({ id, type, events, ...rest }) {
+  const built = { id: `block:ticket:${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:ticket',
+  pageId: 'ticket',
+  blockId: 'ticket',
+  type: 'Box',
+  path: 'ticket',
+  linkPaths: {},
+  subscriptions: [],
+  requests: [],
+  slots: {
+    content: {
+      blocks: [
+        block({
+          id: 'title',
+          type: 'TextInput',
+          events: {
+            onChange: [{ id: 'echo', type: 'SetState', params: { echo: { _state: 'title' } } }],
+          },
+        }),
+        block({ id: 'secret', type: 'TextInput', properties: { type: 'password' } }),
+        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: 'saved', type: 'SetState', params: { saved: true } }],
+          },
+        }),
+      ],
+    },
+  },
+};
+
+const rootConfig = {
+  classMap: {},
+  home: { configured: true, pageId: 'ticket' },
+  lowdefyApp: { slug: 'test-app' },
+  menus: [],
+  pagePaths: { ticket: 'ticket' },
+  theme: { light: {}, dark: {} },
+};
+
+const apiBase = 'http://192.168.1.20:3000';
+
+async function renderTicket() {
+  const fetch = jest.fn();
+  const host = {
+    fetch,
+    globals: createNativeGlobals({
+      assign: jest.fn(),
+      fetch,
+      getPath: () => '/ticket?from=list',
+      origin: apiBase,
+    }),
+    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, auth: { authConfig: {} }, basePath: '', lowdefy };
+  await render(
+    <LowdefyPage
+      core={core}
+      host={host}
+      pageConfig={pageConfig}
+      rootConfig={rootConfig}
+      types={types}
+    />
+  );
+  await screen.findByText('Save');
+  return lowdefy;
+}
+
+function startRecorder(lowdefy) {
+  const posts = [];
+  const fetch = jest.fn(async (url, init) => {
+    posts.push({ url, body: JSON.parse(init.body) });
+    return { ok: true, status: 204 };
+  });
+  const kv = createMemoryStore();
+  const recorder = createNativeRecorder({
+    apiBase,
+    device: 'ios',
+    fetch,
+    getBuild: () => 'build-1',
+    getLowdefy: () => lowdefy,
+    kv,
+    shellVersion: '7.4.0',
+  });
+  recorder.start();
+  return { kv, posts, recorder };
+}
+
+function recordsOf(posts) {
+  return posts.flatMap((post) => post.body.records);
+}
+
+// Times and the session id differ on every run; the fixture keeps their order.
+function normalise(records) {
+  const start = Date.parse('2026-10-18T09:00:00.000Z');
+  return records.map((record, index) => ({
+    ...record,
+    session: '20261018T090000Z-ph0ne1',
+    t: new Date(start + index * 1000).toISOString(),
+  }));
+}
+
+async function act$(callback) {
+  await act(async () => {
+    callback();
+  });
+}
+
+let running;
+afterEach(async () => {
+  await running?.recorder.stop();
+  running = null;
+});
+
+test('a click, a fill and a select are recorded by block id, paired with the events they ran', async () => {
+  const lowdefy = await renderTicket();
+  running = startRecorder(lowdefy);
+  await act$(() => fireEvent.changeText(screen.getByTestId('title_input'), 'Pump'));
+  await act$(() => fireEvent.press(screen.getByTestId('priority-high')));
+  await act$(() => fireEvent.press(screen.getByTestId('save-press')));
+  await running.recorder.flush();
+
+  const { posts } = running;
+  expect(posts.map((post) => post.url)).toEqual([`${apiBase}/api/dev-recording`]);
+  const records = recordsOf(posts);
+  expect(records.every((record) => record.session === posts[0].body.session)).toBe(true);
+  expect(normalise(records)).toEqual(fixture.records);
+});
+
+test('every record passes the trace record validation once the dev server stamps its source', async () => {
+  const lowdefy = await renderTicket();
+  running = startRecorder(lowdefy);
+  await act$(() => fireEvent.changeText(screen.getByTestId('title_input'), 'Pump'));
+  await act$(() => fireEvent.press(screen.getByTestId('save-press')));
+  await running.recorder.flush();
+  const records = recordsOf(running.posts);
+  expect(records.length).toBeGreaterThan(0);
+  records.forEach((record) => {
+    expect(validateTraceRecord({ record: { ...record, source: 'dev' } })).toEqual({});
+  });
+});
+
+test('a password input is never recorded', async () => {
+  const lowdefy = await renderTicket();
+  running = startRecorder(lowdefy);
+  await act$(() => fireEvent.changeText(screen.getByTestId('secret_input'), 'hunter2'));
+  await running.recorder.flush();
+  const change = recordsOf(running.posts).find((record) => record.kind === 'change');
+  expect(change).toMatchObject({ target: { block_id: 'secret' }, value: null, redacted: true });
+  expect(JSON.stringify(recordsOf(running.posts))).not.toContain('hunter2');
+});
+
+test('pressing Enter in an input is recorded as an Enter key on its block', async () => {
+  const lowdefy = await renderTicket();
+  running = startRecorder(lowdefy);
+  await act$(() => fireEvent(screen.getByTestId('title_input'), 'submitEditing'));
+  await running.recorder.flush();
+  const key = recordsOf(running.posts).find((record) => record.kind === 'key');
+  expect(key).toMatchObject({ key: 'Enter', target: { block_id: 'title' }, page_id: 'ticket' });
+});
+
+test('the session is kept in the device store, so a new recorder carries it on', async () => {
+  const lowdefy = await renderTicket();
+  running = startRecorder(lowdefy);
+  await running.recorder.flush();
+  const [first] = recordsOf(running.posts);
+  const again = createNativeRecorder({
+    apiBase,
+    device: 'android',
+    fetch: jest.fn(async () => ({ ok: true })),
+    getBuild: () => null,
+    getLowdefy: () => lowdefy,
+    kv: running.kv,
+    shellVersion: '7.4.0',
+  });
+  const stored = JSON.parse(running.kv.get('lowdefy_dev_recording'));
+  expect(stored.id).toBe(first.session);
+  await again.stop();
+});
+
+test('with no open app the recorder records nothing', async () => {
+  running = startRecorder(null);
+  await running.recorder.flush();
+  expect(running.posts).toEqual([]);
+});

package/src/dev/redirectDevLink.js

@@ -0,0 +1,30 @@
+/*
+  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 parseDevLink from './connection/parseDevLink.js';
+import getShellConfig from '../config/getShellConfig.js';
+
+// Expo Router's redirectSystemPath (app/+native-intent.js): a Lowdefy Dev link is DevShell's, not a
+// page path. Opened with one, the app starts on its home screen; while it runs, the router leaves
+// it alone.
+function redirectDevLink({ initial, path }) {
+  if (parseDevLink({ link: path, scheme: getShellConfig().scheme }) === null) {
+    return path;
+  }
+  return initial ? '/' : null;
+}
+
+export default redirectDevLink;

package/src/dev/redirectDevLink.test.js

@@ -0,0 +1,49 @@
+/*
+  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 { jest } from '@jest/globals';
+
+import redirectDevLink from './redirectDevLink.js';
+
+jest.mock('../config/getShellConfig.js', () => () => ({ scheme: 'lowdefy-dev' }));
+
+const { getShellVariant } = require('../../shellVariant.js');
+
+test('a Lowdefy Dev link is left to DevShell: home on launch, nothing while running', () => {
+  const link = 'lowdefy-dev://connect?url=http%3A%2F%2F192.168.1.20%3A3000&pair=k3x9q';
+  expect(redirectDevLink({ initial: true, path: link })).toBe('/');
+  expect(redirectDevLink({ initial: false, path: link })).toBeNull();
+  expect(redirectDevLink({ initial: false, path: 'lowdefy-dev://menu' })).toBeNull();
+});
+
+test('any other link is routed as a page path', () => {
+  expect(redirectDevLink({ initial: false, path: 'lowdefy-dev://tickets/7' })).toBe(
+    'lowdefy-dev://tickets/7'
+  );
+  expect(redirectDevLink({ initial: true, path: '/tickets/7' })).toBe('/tickets/7');
+});
+
+test('Lowdefy Dev builds as dev and every other shell as release unless the build says', () => {
+  expect(getShellVariant({})).toBe('dev');
+  expect(getShellVariant({ LOWDEFY_SHELL_CONFIG: 'shell.json' })).toBe('release');
+  expect(getShellVariant({ LOWDEFY_SHELL_VARIANT: 'release' })).toBe('release');
+  expect(
+    getShellVariant({ LOWDEFY_SHELL_CONFIG: 'shell.json', LOWDEFY_SHELL_VARIANT: 'dev' })
+  ).toBe('dev');
+  expect(() => getShellVariant({ LOWDEFY_SHELL_VARIANT: 'prod' })).toThrow(
+    'LOWDEFY_SHELL_VARIANT must be "dev" or "release". Received "prod".'
+  );
+});

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;