harmonyc 0.6.0-9 → 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2025 Bernát Kalló
+
+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

@@ -1,57 +1,80 @@
 # Harmony Code
 
-A test design & BDD tool that helps you separate the _what_ to test from the _how_ to automate it. You write test cases in a simple Markdown format, and then automate them with Vitest (and soon with many more frameworks and languages).
+A test design & BDD tool that helps you separate the _what_ to test from the _how_ to automate it. You write test cases in a simple easy-to-read format, and then automate them with Vitest (and soon with other frameworks and languages).
 
-## Usage
+## Setup
 
-- ### watch and run mode
+You need to have Node.js installed. Then you can install Harmony Code in your project folder by:
 
-  - You can compile and run your `*.harmony.md` files in the `src` folder, and watch it, by running
+```bash
+npm install harmonyc
+```
+
+And then run it for all `.harmony` files in your `src` folder:
 
-    ```bash script
-    npx harmonyc --run --watch 'src/**/*.harmony.md'
-    ```
+```bash
+harmonyc src/**/*.harmony
+```
 
-    - => this will generate tests into `*.test.mjs` files
-    - => this will create a stub `*.steps.ts` file if it doesn't exist
+This will generate `.test.mjs` files next to the `.harmony` files, and generate empty definition files for you.
 
 ## Syntax
 
-A Harmony Code file is a Markdown file with a syntax that looks like this:
-
-```markdown
-# Products API
+A `.harmony` file is a text file with a syntax that looks like this:
 
-- **Create**:
-  - **Anonymous:**
-    - create product => error: unauthorized
-  - **Admin**:
-    1. authenticate admin
-    2. create product => product created
-    3. **Delete:**
-       - delete product => product deleted
+```
++ Products API:
+  + Create:
+    + Anonymous:
+      - create product => !! "unauthorized"
+    + Admin:
+      - authenticate with "admin" => product count `0`
+      - create product
+        => product created
+        => product count `1`
+      - Delete:
+        - delete product => product deleted => product count `0`
 ```
 
-### Actions and responses
-
-List items (either in ordered or bulleted lists) consist of an **action** and zero or more **response**s, separated by a `=>`.
+### Indentation
 
-The generated steps contain the feature name after a `||`. Cucumber's steps are in one global namespace, but including the feature name makes it easy to scope step defintions by feature.
+The lines of a file are nodes of a tree. The tree is specified with the indentation of the lines, which is n times 2 spaces and a `+` or `-` with one more space. The `+` or `-` sign is considered to be part of the indentation.
 
 ### Sequences and forks
 
-An ordered list means a **sequence**: the list items are included int the tests in order.
+`-` means a sequence: the node follows the previous sibling node and its descendants.
+
+`+` means a fork: the node directly follows its parent node. All siblings with `+` are separate branches, they will generate separate scenarios.
+
+### Actions and responses (phrases)
 
-A bulleted list (`-` or `*` or `+`) means a **fork**: the node directly follows its parent node. All list items are separate branches, they will generate separate scenarios.
+After the mark, every node can contain an action and zero or more responses. The action is the text before the `=>`, and the responses are the text after the `=>`.
+
+Both actions and responses get compiled to simple function calls - in JavaScript, awaited function calls. The return value of the action is passed to the responses of the same step as the last argument.
+
+### Arguments
+
+Phrases can have arguments which are passed to the implementation function. There are two types of arguments: double-quoted strings are passed to the code as strings, and backtick-quoted strings are passed as is. You can use backticks to pass numbers, booleans, null, or objects.
 
 ### Labels
 
 Label are nodes that end with `:`. You can use them to structure your test design.
 They are not included in the test case, but the test case name is generated from the labels.
 
-### Text
+### Comments
+
+Lines starting with `#` or `//` are comments and are ignored.
+
+### Steps
+
+All other lines are steps. A step consists of an action, and one or more responses denoted by `=>`.
+Actions will become `When` steps, and responses will become `Then` steps.
+
+### Error matching
+
+You can use `!!` to denote an error response. This will verify that the action throws an error. You can specify the error message after the `!!`.
 
-Paragraphs outside of lists are for humans only, they are ignored in the automated tests.
+## Running the tests
 
 ## License
 

package/{cli.js → cli/cli.js}

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { compileFiles } from './compiler.js';
+import { compileFiles } from "../compiler/compiler.js";
 import { parseArgs } from 'node:util';
-import { watchFiles } from './watch.js';
-import { run, runWatch } from './run.js';
+import { watchFiles } from "./watch.js";
+import { run, runWatch } from "./run.js";
 const args = parseArgs({
     options: {
         help: { type: 'boolean' },

package/cli/watch.js

@@ -0,0 +1,35 @@
+import Watcher from 'watcher';
+import { compileFile, compileFiles } from "../compiler/compiler.js";
+export async function watchFiles(patterns) {
+    const { fns, outFns } = await compileFiles(patterns);
+    for (const file of fns) {
+        const watcher = new Watcher(file, { debounce: 20, ignoreInitial: true });
+        watcher.on('all', async () => {
+            var _a;
+            try {
+                await compileFile(file);
+            }
+            catch (e) {
+                process.stdout.write(`\n`);
+                console.log((_a = e.message) !== null && _a !== void 0 ? _a : e);
+                process.stdout.write(`\n`);
+            }
+            logger.log(`Compiled ${file}`);
+        });
+    }
+    return outFns;
+}
+const logger = {
+    last: '',
+    n: 0,
+    log(msg) {
+        if (msg === this.last) {
+            process.stdout.write(`\r${msg} ${++this.n}x`);
+        }
+        else {
+            process.stdout.write(`\r${msg}`);
+            this.last = msg;
+            this.n = 1;
+        }
+    },
+};

package/code_generator/JavaScript.js

@@ -0,0 +1,169 @@
+import { basename } from 'path';
+import { Arg, Word, } from "../model/model.js";
+export class NodeTest {
+    constructor(tf, sf) {
+        this.tf = tf;
+        this.sf = sf;
+        this.framework = 'vitest';
+        this.phraseFns = new Map();
+        this.currentFeatureName = '';
+        this.resultCount = 0;
+        this.extraArgs = [];
+    }
+    feature(feature) {
+        const stepsModule = './' + basename(this.sf.name.replace(/.(js|ts)$/, ''));
+        const fn = (this.currentFeatureName = pascalCase(feature.name));
+        this.phraseFns = new Map();
+        if (this.framework === 'vitest') {
+            this.tf.print(`import { describe, test, expect } from 'vitest';`);
+        }
+        this.tf.print(`import ${fn}Steps from ${str(stepsModule)};`);
+        this.tf.print(``);
+        for (const item of feature.testGroups) {
+            item.toCode(this);
+        }
+        this.sf.print(`export default class ${pascalCase(feature.name)}Steps {`);
+        this.sf.indent(() => {
+            for (const ph of this.phraseFns.keys()) {
+                const p = this.phraseFns.get(ph);
+                const params = p.args.map((a, i) => a.toDeclaration(this, i)).join(', ');
+                this.sf.print(`async ${ph}(${params}) {`);
+                this.sf.indent(() => {
+                    this.sf.print(`throw new Error(${str(`Pending: ${ph}`)});`);
+                });
+                this.sf.print(`}`);
+            }
+        });
+        this.sf.print(`};`);
+    }
+    testGroup(g) {
+        this.tf.print(`describe(${str(g.name)}, () => {`);
+        this.tf.indent(() => {
+            for (const item of g.items) {
+                item.toCode(this);
+            }
+        });
+        this.tf.print('});');
+    }
+    test(t) {
+        this.resultCount = 0;
+        this.featureVars = new Map();
+        // avoid shadowing this import name
+        this.featureVars.set(new Object(), this.currentFeatureName);
+        this.tf.print(`test(${str(t.name)}, async () => {`);
+        this.tf.indent(() => {
+            for (const step of t.steps) {
+                step.toCode(this);
+            }
+        });
+        this.tf.print('});');
+    }
+    errorStep(action, errorMessage) {
+        var _a;
+        this.tf.print(`expect(async () => {`);
+        this.tf.indent(() => {
+            action.toCode(this);
+        });
+        this.tf.print(`}).rejects.toThrow(${(_a = errorMessage === null || errorMessage === void 0 ? void 0 : errorMessage.toCode(this)) !== null && _a !== void 0 ? _a : ''});`);
+    }
+    step(action, responses) {
+        for (const p of [action, ...responses]) {
+            const feature = p.feature.name;
+            let f = this.featureVars.get(feature);
+            if (!f) {
+                f = toId(feature, abbrev, this.featureVars);
+                this.tf.print(`const ${f} = new ${pascalCase(feature)}Steps();`);
+            }
+        }
+        if (responses.length === 0) {
+            action.toCode(this);
+            return;
+        }
+        const res = `r${this.resultCount++ || ''}`;
+        this.tf.print(`const ${res} =`);
+        this.tf.indent(() => {
+            action.toCode(this);
+            try {
+                this.extraArgs = [res];
+                for (const response of responses) {
+                    response.toCode(this);
+                }
+            }
+            finally {
+                this.extraArgs = [];
+            }
+        });
+    }
+    phrase(p) {
+        const phrasefn = this.functionName(p);
+        if (!this.phraseFns.has(phrasefn))
+            this.phraseFns.set(phrasefn, p);
+        const f = this.featureVars.get(p.feature.name);
+        const args = p.args.map((a) => a.toCode(this));
+        args.push(...this.extraArgs);
+        this.tf.print(`await ${f}.${this.functionName(p)}(${args.join(', ')});`);
+    }
+    stringLiteral(text) {
+        return str(text);
+    }
+    codeLiteral(src) {
+        return src;
+    }
+    paramName(index) {
+        return 'xyz'.charAt(index) || `a${index + 1}`;
+    }
+    stringParamDeclaration(index) {
+        return `${this.paramName(index)}: string`;
+    }
+    variantParamDeclaration(index) {
+        return `${this.paramName(index)}: any`;
+    }
+    functionName(phrase) {
+        const { kind } = phrase;
+        return ((kind === 'response' ? 'Then_' : 'When_') +
+            ([...phrase.content, phrase.docstring ? [phrase.docstring] : []]
+                .map((c) => c instanceof Word ? underscore(c.text) : c instanceof Arg ? '_' : '')
+                .filter((x) => x)
+                .join('_') || '_'));
+    }
+}
+function str(s) {
+    if (s.includes('\n'))
+        return '\n' + templateStr(s);
+    let r = JSON.stringify(s);
+    return r;
+}
+function templateStr(s) {
+    return '`' + s.replace(/([`$\\])/g, '\\$1') + '`';
+}
+function capitalize(s) {
+    return s.charAt(0).toUpperCase() + s.slice(1);
+}
+function toId(s, transform, previous) {
+    if (previous.has(s))
+        return previous.get(s);
+    let base = transform(s);
+    let id = base;
+    if ([...previous.values()].includes(id)) {
+        let i = 1;
+        while ([...previous.values()].includes(id + i))
+            i++;
+        id = base + i;
+    }
+    previous.set(s, id);
+    return id;
+}
+function words(s) {
+    return s.split(/[^0-9\p{L}]+/gu);
+}
+function pascalCase(s) {
+    return words(s).map(capitalize).join('');
+}
+function underscore(s) {
+    return words(s).join('_');
+}
+function abbrev(s) {
+    return words(s)
+        .map((x) => x.charAt(0).toUpperCase())
+        .join('');
+}

package/compiler/compile.js

@@ -0,0 +1,32 @@
+import { NodeTest } from "../code_generator/JavaScript.js";
+import { OutFile } from "../code_generator/outFile.js";
+import { parse } from "../parser/parser.js";
+import { base, stepsFileName, testFileName } from "../filenames/filenames.js";
+import { Feature } from "../model/model.js";
+import { basename } from 'node:path';
+import { autoLabel } from "../optimizations/autoLabel/autoLabel.js";
+export function compileFeature(fileName, src) {
+    const feature = new Feature(basename(base(fileName)));
+    try {
+        feature.root = parse(src);
+    }
+    catch (e) {
+        if (e.pos && e.errorMessage) {
+            e.message =
+                e.stack = `Error in ${fileName}:${e.pos.rowBegin}:${e.pos.columnBegin}\n${e.errorMessage}`;
+        }
+        else {
+            e.stack = `Error in ${fileName}\n${e.stack}`;
+        }
+        throw e;
+    }
+    feature.root.setFeature(feature);
+    autoLabel(feature.root);
+    const testFn = testFileName(fileName);
+    const testFile = new OutFile(testFn);
+    const stepsFn = stepsFileName(fileName);
+    const stepsFile = new OutFile(stepsFn);
+    const cg = new NodeTest(testFile, stepsFile);
+    feature.toCode(cg);
+    return { outFile: testFile, stepsFile };
+}

package/{compiler.js → compiler/compiler.js}

@@ -1,11 +1,18 @@
 import glob from 'fast-glob';
 import { existsSync, readFileSync, writeFileSync } from 'fs';
-import { compileFeature } from './compile.js';
+import { resolve } from 'path';
+import { compileFeature } from "./compile.js";
 export async function compileFiles(pattern) {
+    var _a;
     const fns = await glob(pattern);
     if (!fns.length)
         throw new Error(`No files found for pattern: ${String(pattern)}`);
-    const features = await Promise.all(fns.map((fn) => compileFile(fn)));
+    const results = await Promise.allSettled(fns.map((fn) => compileFile(fn)));
+    const features = results.flatMap((r) => r.status === 'fulfilled' ? [r.value] : []);
+    const errors = results.flatMap((r) => r.status === 'rejected' ? [r.reason] : []);
+    for (const error of errors) {
+        console.log((_a = error.message) !== null && _a !== void 0 ? _a : error);
+    }
     console.log(`Compiled ${fns.length} file${fns.length === 1 ? '' : 's'}.`);
     const generated = features.filter((f) => f.stepsFileAction === 'generated');
     if (generated.length) {
@@ -14,7 +21,11 @@ export async function compileFiles(pattern) {
     return { fns, outFns: features.map((f) => f.outFile.name) };
 }
 export async function compileFile(fn) {
-    const src = readFileSync(fn, 'utf8').toString();
+    fn = resolve(fn);
+    const src = readFileSync(fn, 'utf8')
+        .toString()
+        .replace(/\r\n/g, '\n')
+        .replace(/\r/g, '\n');
     const { outFile, stepsFile } = compileFeature(fn, src);
     writeFileSync(outFile.name, outFile.value);
     let stepsFileAction = 'ignored';

package/filenames/filenames.js

@@ -1,7 +1,7 @@
 import glob from 'fast-glob';
 const { globSync, convertPathToPattern } = glob;
 export function base(fn) {
-    return fn.replace(/\.harmony\.md$/i, '');
+    return fn.replace(/\.harmony(\.\w+)?$/i, '');
 }
 export function testFileName(fn) {
     return base(fn) + '.test.mjs';
@@ -9,9 +9,9 @@ export function testFileName(fn) {
 export function stepsFileName(fn) {
     const baseFn = base(fn);
     const pattern = convertPathToPattern(baseFn);
-    const existing = globSync(`${pattern}.steps.*`);
+    const existing = globSync(`${pattern}.steps.{tsx,jsx,ts,js}`);
     if (existing.length) {
-        return existing.sort()[0];
+        return existing.sort().at(-1);
     }
     return `${baseFn}.steps.ts`;
 }

package/{Router.js → model/Router.js}

@@ -1,4 +1,4 @@
-import { xmur3 } from './util/xmur3.js';
+import { xmur3 } from "../util/xmur3.js";
 export class Router {
     constructor(outs, seed = 'TODO') {
         this.outs = outs;