ng-po-gen 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Marian Devecka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+# Description
+
+Allows to auto-generate page objects from Angular templates.
+Uses special HTML attributes to create named bindings for page objects.
+By default the attribute is prefixed by '_'.
+Options may be passed as a value to the attribute to denote usage.
+Currently available options are 'text', 'text-input', 'text-area', 'button', 'checkbox', 'radio-button', 'dropdown', 'select', 'class', 'class={class name}' and 'list'.
+The generator will try to auto detect the type from the html element (e.g. `<input type='checkbox'>` will automatically be resolved as CheckboxObject).
+Attribute names ending with '_list' will treated as list of items.
+Imports and custom code is preserved by default. 
+Custom code needs to be separated by a single line comment.
+If you are using Puppeteer you can use package `npm i puppeteer-page-objects` for the base classes. 
+Otherwise you need to implement base classes for PageObject, ObjectList, TextObject, ButtonObject, CheckboxObject, RadioButtonObject, DropdownObject, TextInputObject and TextAreaObject.
+For more information, please check the test cases inside the test folder or example todo-list application with e2e tests.
+
+## Installation
+
+```bash
+npm i ng-po-gen
+```
+
+## Usage
+
+```bash
+npx ng-po-gen ./src/app --target-dir ./e2e/page-objects
+```
+```
+Angular Page Object Generator
+
+Usage
+
+  ng-po-gen source-dir ...
+
+Options
+
+  --help                      Print this usage guide.
+  --output-dir string         Output directory.
+                              If not specified source directory will be used.
+  --eol string                End of line characters, either "unix" or "win".
+                              Default is "unix".
+  --attribute-prefix string   Prefix of template attribute used by generator.
+                              Default is "_".
+  --selector-prefix string    Optional prefix of angular component tags.
+  --lib string                Import library name used for core page objects.
+                              Default is "puppeteer-page-objects".
+  --overwrite                 Overwrite generated files instead of merge.
+                              Default is false.
+
+```
+
+## Result
+
+### Source Angular Template
+```html
+  <header class="header" _header='class'></header>
+  <main class="items">
+    @if(!loading()){
+      <li class="item-wrapper">
+        @for(item of items();track item.id){
+          <todo-item class="item" [text]="item.text" [completed]="item.completed" 
+                     (textChange)="onTextChanged(item,$event)" (completedChange)="onCompletedChanged(item,$event)" 
+                     (delete)="onItemDelete(item)" _item_list></todo-item>
+        }
+      </li>
+    } @else {
+      <div class="loading" _loading_text>
+        LOADING...
+      </div>
+    }
+  </main>
+  <footer class="footer" _footer='class'></footer>
+```
+
+### Generated Page Object
+```typescript
+import { TextObject, PageObject } from 'puppeteer-page-objects';
+import { HeaderObject } from './header/header.po';
+import { TodoItemObject } from './todo-item/todo-item.po';
+import { FooterObject } from './footer/footer.po';
+
+export class TodoListObject extends PageObject {
+  get header() { return this.createChild(HeaderObject, 'div > header[_header]'); }
+  get itemList() { return this.createList(TodoItemObject, 'div > main > li > todo-item[_item_list]'); }
+  get loadingText() { return this.createChild(TextObject, 'div > main > div[_loading_text]'); }
+  get footer() { return this.createChild(FooterObject, 'div > footer[_footer]'); }
+}
+```
+
+### Example Test
+```typescript
+  ...
+  const app = new TodoListObject(new ObjectContext(page, ['todo-list']));
+  await waitUntil(async () => !(await app.loadingText.visible));
+  await waitUntil(async () => (await app.itemList.length) > 0);
+  ...
+  await app.header.newTaskName.type('wash car\n');
+  await retry([
+    () => expect(app.itemList.length).resolves.toEqual(4),
+    () => expect(app.footer.itemsLeft.text).resolves.toEqual('3 items left'),
+    () => expect(app.itemList.map(i => i.nameText.text)).resolves.toStrictEqual(['buy bannanas', 'do laundry', 'order new sofa', 'wash car']),
+    () => expect(app.itemList.map(i => i.completed)).resolves.toStrictEqual([false, true, false, false]),
+  ]);
+```
+
+For more information check the full todo-list example app with e2e tests in the GitHub repository.

package/bin/ng-po-gen

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../lib/main.js');

package/lib/index.d.ts

@@ -0,0 +1,4 @@
+export * from './main';
+export * from './page-object-builder';
+export * from './template-parser';
+export * from './utils';

package/lib/index.js

@@ -0,0 +1,4 @@
+export * from './main';
+export * from './page-object-builder';
+export * from './template-parser';
+export * from './utils';

package/lib/main.d.ts

@@ -0,0 +1,9 @@
+export interface CmdLineOptions {
+    sourceDir: string;
+    outputDir?: string;
+    eol?: 'unix' | 'win';
+    attributePrefix?: string;
+    selectorPrefix?: string;
+    lib?: string;
+    overwrite?: boolean;
+}

package/lib/main.js

@@ -0,0 +1,96 @@
+import { findComponents } from './utils.js';
+import { TemplateParser } from './template-parser.js';
+import { PageObjectBuilder } from './page-object-builder.js';
+import commandLineArgs from 'command-line-args';
+import commandLineUsage from 'command-line-usage';
+import pc from 'picocolors';
+const cmdLineUsage = [
+    {
+        header: 'Angular Page Object Generator',
+    },
+    {
+        header: 'Usage',
+        content: [
+            'ng-po-gen {underline source-dir} ...',
+        ]
+    },
+    {
+        header: 'Options',
+        optionList: [
+            {
+                name: 'help',
+                description: 'Print this usage guide.',
+                typeLabel: ' '
+            },
+            {
+                name: 'output-dir',
+                description: 'Output directory. \nIf not specified source directory will be used.'
+            },
+            {
+                name: 'eol',
+                description: 'End of line characters, either "unix" or "win". Default is "unix".'
+            },
+            {
+                name: 'attribute-prefix',
+                description: 'Prefix of template attribute used by generator. Default is "_".'
+            },
+            {
+                name: 'selector-prefix',
+                description: 'Optional prefix of angular component tags.'
+            },
+            {
+                name: 'lib',
+                description: 'Import library name used for core page objects. Default is "puppeteer-page-objects".'
+            },
+            {
+                name: 'overwrite',
+                type: Boolean,
+                description: 'Overwrite generated files instead of merge. Default is false.'
+            },
+        ]
+    }
+];
+async function main() {
+    if (process.argv.length < 3 || ['--help', '-h'].includes(process.argv[2])) {
+        const usage = commandLineUsage(cmdLineUsage);
+        console.log(usage);
+        return;
+    }
+    const opt = commandLineArgs([
+        { name: 'source-dir', defaultOption: true },
+        { name: 'output-dir' },
+        { name: 'eol' },
+        { name: 'attribute-prefix' },
+        { name: 'selector-prefix' },
+        { name: 'lib' },
+        { name: 'overwrite', type: Boolean },
+    ], { camelCase: true });
+    if (opt.eol != null && !['unix', 'win'].includes(opt.eol))
+        throw new Error(`unsupported eol '${opt.eol}'`);
+    const parser = new TemplateParser({ attributePrefix: opt.attributePrefix ?? '_' });
+    const builder = new PageObjectBuilder({
+        outputDir: opt.outputDir ?? opt.sourceDir,
+        eol: opt.eol ?? 'unix',
+        selectorPrefix: opt.selectorPrefix ?? '',
+        lib: opt.lib ?? 'puppeteer-page-objects',
+        overwrite: opt.overwrite,
+    });
+    const comps = findComponents(opt.sourceDir);
+    const compMap = new Map(comps.map(c => [c.className, c]));
+    for (const comp of comps) {
+        try {
+            const root = parser.parse(comp);
+            console.log(pc.greenBright(`• ${comp.name}`));
+            await builder.createPageObject(root, compMap);
+        }
+        catch (err) {
+            if (!Array.isArray(err))
+                throw err;
+            console.log(pc.redBright(`• ${comp.name}`));
+            for (const error of err) {
+                console.log(pc.whiteBright(error.msg));
+            }
+        }
+    }
+}
+main().catch(err => console.error(err));

package/lib/page-object-builder.d.ts

@@ -0,0 +1,22 @@
+import { ComponentInfo } from './utils.js';
+import { NodeInfo } from './template-parser.js';
+export interface PageObjectBuilderOptions {
+    outputDir: string;
+    eol: 'unix' | 'win';
+    selectorPrefix: string;
+    lib: string;
+    overwrite?: boolean;
+}
+export declare class PageObjectBuilder {
+    private opt;
+    readonly eolChar: string;
+    constructor(opt: PageObjectBuilderOptions);
+    createPageObject(root: NodeInfo, componentRef: Map<string, ComponentInfo>): Promise<void>;
+    getSourceCode(pageObjectCode: string | null, root: NodeInfo, componentRef: Map<string, ComponentInfo>): Promise<string>;
+    private createClass;
+    private parsePageObject;
+    private getUsedClasses;
+    private getTargetClassInfo;
+    private createRelativePath;
+    private comparePathItems;
+}

package/lib/page-object-builder.js

@@ -0,0 +1,175 @@
+import { TypescriptParser, NamedImport, ClassDeclaration } from 'typescript-parser';
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { convertName, capitalize, ensureDir } from './utils.js';
+import htmlTags from 'html-tags';
+export class PageObjectBuilder {
+    opt;
+    eolChar;
+    constructor(opt) {
+        this.opt = opt;
+        this.eolChar = (opt.eol === 'win') ? '\r\n' : '\n';
+    }
+    async createPageObject(root, componentRef) {
+        const ref = componentRef.get(root.className);
+        const dir = join(this.opt.outputDir, ...ref.pathItems);
+        const path = join(dir, `${ref.name}.po.ts`);
+        const sourceCode = (!this.opt.overwrite && existsSync(path)) ? readFileSync(path, 'utf8') : null;
+        const res = await this.getSourceCode(sourceCode, root, componentRef);
+        ensureDir(dir);
+        writeFileSync(path, res);
+    }
+    async getSourceCode(pageObjectCode, root, componentRef) {
+        const ref = componentRef.get(root.className);
+        let codeInfo = { importedSymbols: new Set(), importedCode: [], keepCode: new Map() };
+        if (pageObjectCode != null) {
+            codeInfo = await this.parsePageObject(pageObjectCode);
+        }
+        let res = '';
+        const usedClasses = this.getUsedClasses(root);
+        const coreImports = Array.from(usedClasses.core).concat('PageObject').filter(i => !codeInfo.importedSymbols.has(i));
+        const otherImports = Array.from(usedClasses.imported).filter(i => !codeInfo.importedSymbols.has(i));
+        for (const code of codeInfo.importedCode) {
+            res += code + this.eolChar;
+        }
+        if (coreImports.length > 0) {
+            res += `import { ${coreImports.join(', ')} } from '${this.opt.lib}';` + this.eolChar;
+        }
+        for (const name of otherImports) {
+            const cref = componentRef.get(name);
+            if (cref != null) {
+                const relPath = this.createRelativePath(ref.pathItems, cref.pathItems);
+                res += `import { ${name} } from '${relPath}/${cref.name}.po';` + this.eolChar;
+            }
+        }
+        const visitNodes = (nodeInfo) => {
+            if (nodeInfo.children.length > 0) {
+                res += this.eolChar;
+                res += this.createClass(nodeInfo, codeInfo.keepCode.get(nodeInfo.className));
+            }
+            for (const child of nodeInfo.children) {
+                visitNodes(child);
+            }
+        };
+        visitNodes(root);
+        return res;
+    }
+    createClass(info, mergeCode) {
+        let res = `export class ${info.className} extends PageObject {` + this.eolChar;
+        for (const child of info.children) {
+            const isList = (child.selector && child.selector.endsWith('_list')) || child.options.includes('list');
+            const funcName = (isList) ? 'this.createList' : 'this.createChild';
+            const name = (isList) ? `${child.propName}List` : child.propName;
+            const selector = child.selectorPath.join(' > ').trim();
+            const className = this.getTargetClassInfo(child)[0];
+            res += `  get ${name}() { return ${funcName}(${className}, '${selector}'); }` + this.eolChar;
+        }
+        if (mergeCode != null) {
+            res += mergeCode + this.eolChar;
+        }
+        else {
+            res += "}" + this.eolChar;
+        }
+        return res;
+    }
+    async parsePageObject(sourceCode) {
+        const parser = new TypescriptParser();
+        const comments = Array.from(sourceCode.matchAll(/[ \t]*\/\/.*\r?\n/g));
+        const codeInfo = await parser.parseSource(sourceCode);
+        const importedSymbols = new Set();
+        const importedCode = [];
+        for (const item of codeInfo.imports) {
+            if (item instanceof NamedImport) {
+                for (const specifier of item.specifiers) {
+                    importedSymbols.add(specifier.alias ?? specifier.specifier);
+                }
+                importedCode.push(sourceCode.substring(item.start, item.end));
+            }
+        }
+        const keepCode = new Map();
+        for (const decl of codeInfo.declarations) {
+            if (decl instanceof ClassDeclaration) {
+                const firstClassComment = comments.find(c => c.index >= decl.start && c.index <= decl.end);
+                if (firstClassComment != null) {
+                    keepCode.set(decl.name, sourceCode.substring(firstClassComment.index, decl.end));
+                }
+            }
+        }
+        return { importedSymbols, importedCode, keepCode };
+    }
+    getUsedClasses(root) {
+        const core = new Set();
+        const imported = new Set();
+        const visitNodes = (nodeInfo) => {
+            const [targetClass, origin] = this.getTargetClassInfo(nodeInfo);
+            if (origin === 'core') {
+                core.add(targetClass);
+            }
+            else if (origin === 'import') {
+                imported.add(targetClass);
+            }
+            for (const child of nodeInfo.children) {
+                visitNodes(child);
+            }
+        };
+        visitNodes(root);
+        return { core, imported };
+    }
+    getTargetClassInfo(info) {
+        const classMap = new Map([
+            ['text', 'TextObject'],
+            ['text-input', 'TextInputObject'],
+            ['text-area', 'TextAreaObject'],
+            ['button', 'ButtonObject'],
+            ['checkbox', 'CheckboxObject'],
+            ['radio-button', 'RadioButtonObject'],
+            ['dropdown', 'DropdownObject'],
+            ['select', 'DropdownObject'],
+        ]);
+        const classAlias = info.options.find(opt => classMap.has(opt));
+        if (classAlias != null)
+            return [classMap.get(classAlias), 'core'];
+        const classOption = info.options.find(o => o.startsWith('class='));
+        if (classOption != null) {
+            const className = classOption.substring(6).trim();
+            return [className, 'import'];
+        }
+        if (!htmlTags.includes(info.nodeType) || info.options.includes('class')) {
+            const prefix = this.opt.selectorPrefix;
+            return [capitalize(convertName(info.nodeType.substring(prefix.length))) + 'Object', 'import'];
+        }
+        if (info.children.length === 0) {
+            if (info.nodeType === 'input') {
+                if (info.typeAttr === 'checkbox')
+                    return ['CheckboxObject', 'core'];
+                if (info.typeAttr === 'radio')
+                    return ['RadioButtonObject', 'core'];
+                return ['TextInputObject', 'core'];
+            }
+            if (info.nodeType === 'button') {
+                return ['ButtonObject', 'core'];
+            }
+            if (info.nodeType === 'textarea') {
+                return ['TextAreaObject', 'core'];
+            }
+            if (info.nodeType === 'select') {
+                return ['DropdownObject', 'core'];
+            }
+            return ['TextObject', 'core'];
+        }
+        return [info.className, 'new'];
+    }
+    createRelativePath(path1, path2) {
+        const count = this.comparePathItems(path1, path2);
+        const diff = path1.length - count;
+        const prefix = (diff === 0) ? './' : '../'.repeat(diff);
+        return prefix + path2.slice(count).join('/');
+    }
+    comparePathItems(path1, path2) {
+        let i = 0;
+        while (path1.length > i && path2.length > i && path1[i] === path2[i]) {
+            i++;
+        }
+        return i;
+    }
+}

package/lib/template-parser.d.ts

@@ -0,0 +1,25 @@
+import { Element } from 'angular-html-parser/lib/compiler/src/ml_parser/ast.js';
+import { ComponentInfo } from './utils.js';
+export interface NodeInfo {
+    propName: string;
+    className: string;
+    nodeType: string;
+    typeAttr?: string;
+    namePath: string[];
+    selector?: string;
+    selectorPath: string[];
+    options: string[];
+    children: NodeInfo[];
+    node?: Element;
+}
+export interface TemplateParserOptions {
+    attributePrefix: string;
+}
+export declare class TemplateParser {
+    private opt;
+    constructor(opt: TemplateParserOptions);
+    parse(info: ComponentInfo): NodeInfo;
+    parseTemplate(templateName: string, templateText: string): NodeInfo;
+    private parseNodes;
+    private getClassName;
+}

package/lib/template-parser.js

@@ -0,0 +1,71 @@
+import { parse } from 'angular-html-parser';
+import { Element } from 'angular-html-parser/lib/compiler/src/ml_parser/ast.js';
+import { readFileSync } from 'fs';
+import { convertName, capitalize } from './utils.js';
+export class TemplateParser {
+    opt;
+    constructor(opt) {
+        this.opt = opt;
+    }
+    parse(info) {
+        const contents = readFileSync(info.path, 'utf8');
+        return this.parseTemplate(info.name, contents);
+    }
+    parseTemplate(templateName, templateText) {
+        const { rootNodes, errors } = parse(templateText);
+        if (errors.length > 0)
+            throw errors;
+        const nodeName = convertName(templateName);
+        const root = {
+            propName: nodeName,
+            className: this.getClassName([nodeName]),
+            nodeType: 'body',
+            namePath: [nodeName],
+            selectorPath: [],
+            options: [],
+            children: [],
+        };
+        this.parseNodes(root, rootNodes);
+        return root;
+    }
+    parseNodes(parent, nodes, path = []) {
+        for (const node of nodes) {
+            if (node instanceof Element) {
+                const prefix = this.opt.attributePrefix;
+                const idAttr = node.attrs.find(attr => attr.name.startsWith(prefix));
+                const typeAttr = node.attrs.find(attr => attr.name === 'type');
+                if (node.name === 'ng-container' || idAttr?.name === '__ignore') {
+                    this.parseNodes(parent, node.children, path);
+                }
+                else if (idAttr != null) {
+                    const name = convertName(idAttr.name.substring(prefix.length).replace(/_list$/, ''));
+                    const selector = `${node.name}[${idAttr.name}]`;
+                    const options = (idAttr.value ?? '').split(',').map(i => i.trim());
+                    const namePath = [...parent.namePath, name];
+                    const item = {
+                        propName: name,
+                        className: this.getClassName(namePath),
+                        nodeType: node.name,
+                        typeAttr: typeAttr?.value,
+                        selector: idAttr.name,
+                        options: options,
+                        node: node,
+                        namePath: namePath,
+                        selectorPath: [...path, selector],
+                        children: [],
+                    };
+                    parent.children.push(item);
+                    this.parseNodes(item, node.children, ['']);
+                }
+                else {
+                    const selector = node.name;
+                    this.parseNodes(parent, node.children, [...path, selector]);
+                }
+            }
+        }
+    }
+    getClassName(namePath) {
+        const name = namePath.map(p => capitalize(p)).join('');
+        return name + 'Object';
+    }
+}

package/lib/utils.d.ts

@@ -0,0 +1,10 @@
+export interface ComponentInfo {
+    name: string;
+    className: string;
+    pathItems: string[];
+    path: string;
+}
+export declare function findComponents(basePath: string): ComponentInfo[];
+export declare function capitalize(name: string): string;
+export declare function convertName(name: string): string;
+export declare function ensureDir(path: string): void;

package/lib/utils.js

@@ -0,0 +1,57 @@
+import { readdirSync, mkdirSync, existsSync, lstatSync } from 'fs';
+import { join, parse } from 'path';
+export function findComponents(basePath) {
+    const result = [];
+    const visit = (basePath, pathItems) => {
+        const path = join(basePath, ...pathItems);
+        const items = readdirSync(path);
+        for (const item of items) {
+            const { ext, name } = parse(item);
+            const filePath = join(path, item);
+            const stats = lstatSync(filePath);
+            if (stats.isDirectory()) {
+                visit(basePath, [...pathItems, item]);
+                continue;
+            }
+            if (stats.isFile() && ext === '.html') {
+                const componentName = name.replace(/\.component$/, '');
+                const info = {
+                    name: componentName,
+                    className: capitalize(convertName(componentName)) + 'Object',
+                    pathItems: pathItems,
+                    path: filePath,
+                };
+                result.push(info);
+            }
+        }
+    };
+    visit(basePath, []);
+    return result;
+}
+export function capitalize(name) {
+    return (name.length === 0) ? name : name[0].toUpperCase() + name.substring(1);
+}
+export function convertName(name) {
+    let result = "";
+    let cap = false;
+    for (let i = 0; i < name.length; i++) {
+        const ch = name[i];
+        if (ch === '_' || ch === '-') {
+            cap = (i !== 0);
+            continue;
+        }
+        if (cap) {
+            result += ch.toUpperCase();
+            cap = false;
+        }
+        else {
+            result += ch;
+        }
+    }
+    return result;
+}
+export function ensureDir(path) {
+    if (!existsSync(path)) {
+        mkdirSync(path, { recursive: true });
+    }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "ng-po-gen",
+  "version": "1.0.0",
+  "author": "Marian Devecka",
+  "license": "MIT",
+  "description": "Allows to auto-generate page objects from Angular templates.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mdevecka/ng-po-gen"
+  },
+  "keywords": [
+    "typescript",
+    "angular",
+    "testing",
+    "page objects"
+  ],
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "bin": {
+    "ng-po-gen": "./bin/ng-po-gen"
+  },
+  "dependencies": {
+    "angular-html-parser": "^9.2.0",
+    "command-line-args": "^6.0.1",
+    "command-line-usage": "^7.0.3",
+    "html-tags": "^5.0.0",
+    "picocolors": "^1.1.1",
+    "typescript-parser": "^2.6.1"
+  },
+  "sideEffects": false,
+  "files": [
+    "**/*.js",
+    "**/*.d.ts"
+  ]
+}