@lowdefy/e2e-utils 5.2.0 → 5.4.0

package/README.md

@@ -89,6 +89,44 @@ test('validates required fields', async ({ ldf }) => {
 });
 ```
 
+### Testing List Children (`ldf.list()` / `ldf.block()` with indexed ids)
+
+List blocks render their slot children with runtime-prefixed ids
+(`legal_rows.0.toggle`, `legal_rows.1.toggle`, ...). You can pass these indexed ids
+straight into `ldf.block()` — the manifest stores `legal_rows.$.toggle` and the runtime
+resolves the numeric segment automatically:
+
+```javascript
+await ldf.block('legal_rows.0.toggle').do.toggle();
+await ldf.block('legal_rows.0.toggle').expect.checked();
+```
+
+For ergonomic row addressing, use `ldf.list(listId)`:
+
+```javascript
+// Number of rows in state
+const count = await ldf.list('legal_rows').count();
+
+// Positional access (synchronous)
+await ldf.list('legal_rows').row(0).block('toggle').do.toggle();
+
+// By key (async — reads list state to find the index)
+const row = await ldf.list('legal_rows').rowBy('_id', 'bbbee');
+await row.block('toggle').do.toggle();
+await row.block('toggle').expect.checked();
+
+// By predicate (async)
+const archived = await ldf.list('legal_rows').rowWhere((it) => it.archived === true);
+await archived.block('restore_btn').do.click();
+```
+
+Nested lists work the same way — every level of nesting adds another numeric
+segment, all resolved through one templated lookup:
+
+```javascript
+await ldf.block('outer.0.inner.2.button').do.click();
+```
+
 ### State (`ldf.state()`)
 
 ```javascript

package/dist/proxy/createPageManager.js

@@ -22,6 +22,7 @@ import { expectUrl, expectUrlQuery, setUrlQuery } from '../core/url.js';
 import { setUserCookie, clearUserCookie } from '../core/userCookie.js';
 import { get, type } from '@lowdefy/helpers';
 import createBlockMethodProxy from './createBlockMethodProxy.js';
+import resolveTemplateId from './resolveTemplateId.js';
 function createPageManager({ page, manifest, helperRegistry, mockManager }) {
     let currentBlockMap = null;
     let currentPageId = null;
@@ -30,6 +31,81 @@ function createPageManager({ page, manifest, helperRegistry, mockManager }) {
             throw new Error('Call goto() before accessing blocks');
         }
     }
+    // Block locator - ldf.block('id').do.*/expect.*/locator()/state()/validation()
+    // List children: pass the concrete runtime blockId (e.g. `legal_rows.0.toggle`) and we
+    // fall back to the templated entry (`legal_rows.$.toggle`) for the type/helper. The
+    // concrete blockId still flows into each helper's locator(page, blockId) so the DOM
+    // selector targets the right row.
+    function block(blockId) {
+        ensurePageLoaded();
+        let blockInfo = currentBlockMap[blockId];
+        if (!blockInfo) {
+            const templateId = resolveTemplateId(blockId);
+            if (templateId !== blockId) {
+                blockInfo = currentBlockMap[templateId];
+            }
+        }
+        if (!blockInfo) {
+            const available = Object.keys(currentBlockMap).join(', ');
+            throw new Error(`Block "${blockId}" not found on page. Available blocks: ${available || '(none)'}`);
+        }
+        return {
+            do: createBlockMethodProxy({
+                page,
+                blockId,
+                blockInfo,
+                helperRegistry,
+                mode: 'do'
+            }),
+            expect: createBlockMethodProxy({
+                page,
+                blockId,
+                blockInfo,
+                helperRegistry,
+                mode: 'expect'
+            }),
+            locator: ()=>getBlock(page, blockId),
+            state: ()=>getBlockState(page, {
+                    blockId
+                }),
+            validation: ()=>getValidation(page, blockId)
+        };
+    }
+    // List locator - ldf.list('id') for ergonomic addressing of list children.
+    //   .count()                  → number of items currently in state
+    //   .row(i).block('childId')  → synchronous, positional access
+    //   .rowBy('_id', 'bbbee')    → async; resolves to a row whose block(...) is sync
+    //   .rowWhere(item => ...)    → async; same shape as rowBy
+    // All paths delegate to block(`${listId}.${index}.${childId}`), so the templated
+    // manifest lookup above takes over from there.
+    function list(listId) {
+        ensurePageLoaded();
+        const readItems = async ()=>{
+            const state = await getState(page);
+            const items = get(state, listId);
+            if (!Array.isArray(items)) {
+                throw new Error(`ldf.list("${listId}"): state value is not an array (got ${items === undefined ? 'undefined' : typeof items}). Make sure a Request has populated the list state before reading rows.`);
+            }
+            return items;
+        };
+        const rowAt = (index)=>({
+                block: (childId)=>block(`${listId}.${index}.${childId}`)
+            });
+        const findRow = async (predicate, describe)=>{
+            const items = await readItems();
+            const index = items.findIndex(predicate);
+            if (index < 0) {
+                throw new Error(`ldf.list("${listId}"): no row matched ${describe}.`);
+            }
+            return rowAt(index);
+        };
+        return {
+            count: async ()=>(await readItems()).length,
+            row: (index)=>rowAt(index),
+            rowBy: (key, value)=>findRow((item)=>item != null && item[key] === value, `${key}=${JSON.stringify(value)}`),
+            rowWhere: (predicate)=>findRow(predicate, 'predicate')
+        };
+    }
     return {
         // Raw Playwright page
         page,
@@ -60,36 +136,8 @@ function createPageManager({ page, manifest, helperRegistry, mockManager }) {
         get pageId () {
             return currentPageId;
         },
-        // Block locator - ldf.block('id').do.*/expect.*/locator()/state()/validation()
-        block (blockId) {
-            ensurePageLoaded();
-            const blockInfo = currentBlockMap[blockId];
-            if (!blockInfo) {
-                const available = Object.keys(currentBlockMap).join(', ');
-                throw new Error(`Block "${blockId}" not found on page. Available blocks: ${available || '(none)'}`);
-            }
-            return {
-                do: createBlockMethodProxy({
-                    page,
-                    blockId,
-                    blockInfo,
-                    helperRegistry,
-                    mode: 'do'
-                }),
-                expect: createBlockMethodProxy({
-                    page,
-                    blockId,
-                    blockInfo,
-                    helperRegistry,
-                    mode: 'expect'
-                }),
-                locator: ()=>getBlock(page, blockId),
-                state: ()=>getBlockState(page, {
-                        blockId
-                    }),
-                validation: ()=>getValidation(page, blockId)
-            };
-        },
+        block,
+        list,
         // Request locator - ldf.request('id').expect.*/response()/state()
         request (requestId) {
             return {

package/dist/proxy/resolveTemplateId.js

@@ -0,0 +1,21 @@
+/*
+  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.
+*/ // Convert a runtime blockId (e.g. `legal_rows.0.toggle`) into the template form
+// stored in the e2e manifest (`legal_rows.$.toggle`) by replacing each integer-only
+// dot-separated segment with `$`. Mixed segments like `step_1d` are left as-is.
+function resolveTemplateId(blockId) {
+    return blockId.split('.').map((segment)=>/^\d+$/.test(segment) ? '$' : segment).join('.');
+}
+export default resolveTemplateId;

package/dist/testPrep/extractBlockMap.js

@@ -18,34 +18,46 @@
     if (container['~arr']) return container['~arr'];
     return [];
 }
-function extractBlockMap({ pageConfig, typesBlocks }) {
+function extractBlockMap({ pageConfig, typesBlocks, blockMetas = {} }) {
     const blockMap = {};
-    function traverse(obj) {
+    function traverse(obj, prefix) {
         if (!obj || typeof obj !== 'object') return;
-        // If this object has blockId and type, record it
+        let nextPrefix = prefix;
+        // If this object has blockId and type, record it under prefix + blockId.
+        // List-category blocks (category: 'list' on their meta) iterate their slot children
+        // at runtime under {blockId}.{index}.{childId}, so we record children under the
+        // template id `{blockId}.$.{childId}` and downstream resolves numeric runtime
+        // segments back to `$` for lookup.
         if (obj.blockId && obj.type) {
             const packageName = typesBlocks[obj.type]?.package;
             if (packageName) {
-                blockMap[obj.blockId] = {
+                blockMap[`${prefix}${obj.blockId}`] = {
                     type: obj.type,
                     helper: `${packageName}/e2e`
                 };
             }
+            if (blockMetas[obj.type]?.category === 'list') {
+                nextPrefix = `${prefix}${obj.blockId}.$.`;
+            }
+        }
+        // Traverse slots - slot.blocks is { "~arr": [...blocks...] }
+        if (obj.slots) {
+            Object.values(obj.slots).forEach((slot)=>{
+                getBlocksArray(slot.blocks).forEach((block)=>traverse(block, nextPrefix));
+            });
         }
         // Traverse areas - area.blocks is { "~arr": [...blocks...] }
         if (obj.areas) {
             Object.values(obj.areas).forEach((area)=>{
-                const blocks = getBlocksArray(area.blocks);
-                blocks.forEach((block)=>traverse(block));
+                getBlocksArray(area.blocks).forEach((block)=>traverse(block, nextPrefix));
             });
         }
         // Traverse direct blocks array (may also be { "~arr": [...] })
         if (obj.blocks) {
-            const blocks = getBlocksArray(obj.blocks);
-            blocks.forEach((block)=>traverse(block));
+            getBlocksArray(obj.blocks).forEach((block)=>traverse(block, nextPrefix));
         }
     }
-    traverse(pageConfig);
+    traverse(pageConfig, '');
     return blockMap;
 }
 export default extractBlockMap;

package/dist/testPrep/generateManifest.js

@@ -21,6 +21,11 @@ function generateManifest({ buildDir = '.lowdefy' }) {
         throw new Error(`Build artifacts not found at ${buildDir}. Run 'lowdefy build' first.`);
     }
     const types = JSON.parse(fs.readFileSync(typesPath, 'utf-8'));
+    // blockMetas tells us which block types iterate their slot children (category === 'list').
+    // Missing file is non-fatal: older builds keep working, list children just don't get the
+    // .$. prefix applied.
+    const blockMetasPath = path.join(buildDir, 'plugins/blockMetas.json');
+    const blockMetas = fs.existsSync(blockMetasPath) ? JSON.parse(fs.readFileSync(blockMetasPath, 'utf-8')) : {};
     const pagesDir = path.join(buildDir, 'pages');
     const manifest = {
         pages: {}
@@ -42,7 +47,8 @@ function generateManifest({ buildDir = '.lowdefy' }) {
                     const pageConfig = JSON.parse(fs.readFileSync(pageConfigPath, 'utf-8'));
                     manifest.pages[pageId] = extractBlockMap({
                         pageConfig,
-                        typesBlocks: types.blocks ?? {}
+                        typesBlocks: types.blocks ?? {},
+                        blockMetas
                     });
                 }
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lowdefy/e2e-utils",
-  "version": "5.2.0",
+  "version": "5.4.0",
   "license": "Apache-2.0",
   "description": "Lowdefy E2E Testing Utilities for Playwright",
   "homepage": "https://lowdefy.com",
@@ -36,7 +36,7 @@
     "dist/*"
   ],
   "dependencies": {
-    "@lowdefy/helpers": "5.2.0",
+    "@lowdefy/helpers": "5.4.0",
     "js-yaml": "4.1.0",
     "prompts": "2.4.2"
   },