harmonyc 0.22.0 → 0.23.0

package/README.md

@@ -1,142 +1,271 @@
 # Harmony Code
 
-A test design & BDD tool that helps you separate _what_ you test and _how_ you automate it. You write test cases in a simple easy-to-read format, and then automate them with Vitest.
+**Write unit tests that speak human language**
 
-## Setup
+Harmony Code transforms how you write and maintain tests. Instead of wrestling with complex test code, you describe _what_ you want to test in plain English (or whichever language), and Harmony generates the Vitest test code for you.
 
-You need to have Node.js installed. Then you can install Harmony Code in your project folder by:
+## ✨ Why Harmony Code?
+
+**💭 Think in scenarios, not syntax**  
+Focus on business logic and user flows instead of test framework boilerplate.
+
+**📖 Tests as living documentation**  
+Your `.harmony` files become readable specifications that anyone can understand.
+
+**🖇️ Separation of concerns**  
+Test design (`.harmony`) stays separate from test implementation (`.phrases.ts`).
+
+**⚡ Vitest integration**  
+Get all the benefits of Vitest's speed and developer experience.
+
+## 🚀 Quick Start
+
+### 1. Install Harmony Code
 
 ```bash
 npm install harmonyc
 ```
 
-Then add it as a plugin to your `vitest.config.js` or `vite.config.js` file, and make sure to include your `.harmony` files:
+### 2. Configure Vitest
+
+Add Harmony plugin to your `vitest.config.js` or `vite.config.js` and include `.harmony` files in tests:
 
 ```js
 import harmony from 'harmonyc/vitest'
 
 export default {
   plugins: [harmony()],
-  include: ['src/**/*.harmony'],
+  test: {
+    include: ['**/*.{test,spec}.{js,ts}', '**/*.harmony'],
+  },
 }
 ```
 
-This will run .harmony files in vitest.
+### 3. Write your first test
 
-## VSCode plugin
+Create `formatCurrency.harmony`:
 
-Harmony Code has a [VSCode plugin](https://marketplace.visualstudio.com/items?itemName=harmony-ac.harmony-code) that supports syntax highlighting.
+```harmony
+# Currency Formatting
 
-Harmony Code is compatible with Vitest's VSCode plugin, so you can run and debug tests from the editor.
++ Dollar formatting:
+  - format amount `123.45` => "$123.45"
+  - format amount `100` => "$100.00"
 
-## Syntax
++ Euro formatting:
+  - format amount `67.98` with "EUR" => "€67.98"
+```
+
+### 4. Implement test steps
+
+Harmony automatically generates `formatCurrency.phrases.ts` for you, adding new method stubs and keeping your existing implementations. It intelligently sorts methods alphabetically within `When_` and `Then_` categories. Fill them in like this:
+
+```typescript
+import { expect } from 'vitest'
+import { formatCurrency } from '../src/currency'
 
-A `.harmony` file is a text file with a syntax that looks like this:
+export default class FormatCurrencyPhrases {
+  async When_format_amount_X(amount: number) {
+    return formatCurrency(amount)
+  }
 
+  async When_format_amount_X_with_Y(amount: number, currency: string) {
+    return formatCurrency(amount, currency)
+  }
+
+  async Then_X(expected: string, actual: string) {
+    expect(actual).toBe(expected)
+  }
+}
 ```
-+ 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`
+
+### 5. Run your tests
+
+```bash
+npx vitest
 ```
 
-### Indentation
+That's it! Your tests run just like regular Vitest tests, but with the clarity of human language.
 
-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.
+## 🛠 IDE Support
 
-### Sequences and forks
+**VS Code Extension**: Get syntax highlighting and IntelliSense for `.harmony` files.
 
-`-` means a sequence: the node follows the previous sibling node and its descendants.
+Install: [Harmony Code Extension](https://marketplace.visualstudio.com/items?itemName=harmony-ac.harmony-code)
 
-`+` means a fork: the node directly follows its parent node. All siblings with `+` are separate branches, they will generate separate scenarios.
+**Vitest Integration**: Run and debug tests directly from VS Code using the official Vitest extension.
 
-### Phrases (actions and responses)
+## 📚 Harmony Code Syntax Guide
 
-After the mark, every node can contain an **action** and zero or more **responses**, together called **phrases**. The action is the text before the `=>`, and the responses are the text after the `=>`.
+### Test Structure
 
-Both actions and responses get compiled to simple function calls - in JavaScript, awaited function calls. Actions will become `When_*` functions, and responses will become `Then_*` functions. The return value of the action is passed to the responses of the same step as the last argument.
+Harmony Code uses indentation and symbols to create test scenarios:
 
-### Arguments
+- **`+ `** creates test **forks** - each becomes a separate test case
+- **`- `** creates **sequential steps** within the same test case
+- **Lines ending with `:`** are sections for organizing tests
 
-Phrases (actions and responses) can have arguments which are passed to the implementation function. There are two types of arguments: strings and code fragments:
+### Actions and Expectations
+
+Each step can have an action and expected outcomes:
 
 ```harmony
-+ strings:
-  + hello "John"
-+ code fragment:
-  + greet `3` times
+- action => expected result
+- action => !! "expected error message"
 ```
 
-becomes
-
-```javascript
-test('T1 - strings', async () => {
-  const P = new Phrases()
-  await P.When_hello_('John')
-})
-test('T2 - code fragment', async () => {
-  const P = new Phrases()
-  await P.When_greet__times(3)
-})
-```
+**Actions** become `When_*` methods, **expectations** become `Then_*` methods.
 
-### Labels
+### Parameters
 
-Labels are lines that start with `-` or `+` and 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.
+Use quotes for strings and backticks for other values:
+
+```harmony
+- login with "john@example.com" remember `true` => user logged in
+```
 
-### Comments
+Becomes:
 
-Lines starting with `#` or `//` are comments and are ignored.
+```typescript
+async When_login_with_X_remember_Y(email: string, rememberMe: boolean) {
+  // your implementation
+}
+```
 
-### Switches
+Parameters are mapped to `X`, `Y`, `Z`, `A`, `B`, `C`... (alphabetically) in method names.
 
-You can generate multiple test cases by adding a `{ A / B / C }` syntax into action(s) and possibly response(s).
+### Example: User Authentication
 
 ```harmony
-+ password is { "A" / "asdf" / "password123" } => !! "password is too weak"
+# User Authentication
+
++ successful login:
+  - enter email "user@test.com"
+  - enter password "password123"
+  - click login button => redirected to dashboard
+
++ failed login:
+  - enter email "wrong@test.com"
+  - enter password "wrongpass"
+  - click login button => !! "Invalid credentials"
+
++ password requirements:
+  + too short:
+    - set password "123" => !! "Password must be at least 8 characters"
+  + missing special character:
+    - set password "password123" => !! "Password must contain a special character"
 ```
 
-### Error matching
+## 🔄 How It Works
+
+1. **Write scenarios** in `.harmony` files using human-readable language
+2. **Harmony generates** the corresponding Vitest test structure
+3. **Harmony updates** your `.phrases.ts` files, adding new method stubs while preserving existing implementations
+4. **You implement** the step methods (only the new ones need your attention)
+5. **Run tests** with Vitest watch mode automatically, or with VSCode Vitest extension
+
+The beauty is in the separation: your test scenarios remain clean and business-focused, while implementation details live in separate files.
 
-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 `!!`.
+### Smart Code Generation
+
+- **Preserves your work**: Existing method implementations are never overwritten
+- **Adds only what's needed**: New method stubs are generated for missing steps
+- **Removes unused methods**: Methods no longer referenced in `.harmony` files are cleaned up
+- **Keeps things organized**: Methods are sorted alphabetically within `When_` and `Then_` categories
+
+## 🎯 Advanced Features
 
 ### Variables
 
-You can set variables in the tests and use them in strings and code fragments:
+Store and reuse values across test steps:
+
+```harmony
++ user workflow:
+  - create user => ${userId}
+  - login with user id "${userId}" => success
+  - delete user "${userId}" => user removed
+```
+
+### Test Switches
+
+Generate multiple test cases with variations:
 
+```harmony
++ password validation:
+  - password { "123" / "abc" / "" } => !! "Invalid password"
 ```
-+ set variable:
-  + ${name} "John"
-    + greet "${name}" => "hello John"
-+ store result into variable:
-  + run process => ${result}
-    + "${result}" is "success"
+
+This creates three separate test cases, one for each password value.
+
+### Error Testing
+
+Use `!!` to test error conditions. The error message is optional - if provided, it checks that the thrown error contains that substring:
+
+```harmony
++ division by zero:
+  - divide `10` by `0` => !! "Cannot divide by zero"
+  - divide `5` by `0` => !!  # just checks that an error is thrown
 ```
 
-becomes
-
-```javascript
-test('T1 - set variable', (context) => {
-  const P = new Phrases();
-  (context.task.meta.variables ??= {})['name'] = "John";
-  await P.When_greet_(context.task.meta.variables?.['name']);
-})
-test('T2 - store result in variable', (context) => {
-  const P = new Phrases();
-  const r = await P.When_run_process();
-  (context.task.meta.variables ??= {})['result'] = r;
-  await P.Then__is_(`${context.task.meta.variables?.['result']});
-})
+**No implementation needed**: Error steps don't require corresponding methods in your phrases file.
+
+### Complex Scenarios
+
+Build sophisticated test flows:
+
+```harmony
+# E-commerce Checkout
+
++ guest checkout:
+  - add product "T-shirt" to cart
+  - go to checkout
+  - enter shipping address:
+    - name "John Doe"
+    - address "123 Main St"
+  - select payment method "credit card"
+  - complete purchase => order confirmation
+
++ member checkout:
+  - login as "member@test.com"
+  - add product "Laptop" to cart
+  - use saved address => address populated
+  - complete purchase => order confirmation
+  - check order history => order appears
 ```
 
-## License
+## 🧹 Best Practices
+
+**Use natural language**: Write steps as if explaining to a manual tester. Write in the language you use for discussing requirements.  
+**Keep scenarios focused**: Each test should verify one main behavior  
+**Use descriptive names**: Make test intentions clear from the scenario text  
+**Use parameter-only names** if there is an obivous single-parameter input or output (e.g., `` => `true` ``, which will be `Then_X(x)` )  
+**Group related tests**: Use sections (lines ending with `:`) to organize  
+**Test edge cases**: Include error conditions and boundary values  
+**Maintain phrase files**: Keep step implementations simple and focused, add JSDoc if step documentation is needed
+
+## ⌨️ CLI Usage
+
+Compile `.harmony` files manually:
+
+```bash
+npx harmonyc "src/**/*.harmony"
+```
+
+Watch for changes:
+
+```bash
+npx harmonyc "src/**/*.harmony" --watch
+```
+
+## 📦 Package Structure
+
+- **`harmonyc`** - Core compiler and Vitest plugin
+- **VS Code Extension** - Syntax highlighting and language support
+
+## 🤝 Contributing
+
+Harmony Code is open source and welcomes contributions. Check out our [GitHub repository](https://github.com/harmony-ac/code) for issues, feature requests, and development setup.
+
+## 📄 License
 
-MIT
+MIT - see [LICENSE](LICENSE) for details.

package/dist/code_generator/VitestGenerator.js

@@ -22,7 +22,7 @@ export class VitestGenerator {
         this.extraArgs = [];
     }
     feature(feature) {
-        const phrasesModule = './' + basename(this.sourceFileName.replace(/\.harmony$/, '.phrases.js'));
+        const phrasesModule = './' + basename(this.sourceFileName.replace(/\.harmony$/, '.phrases'));
         const fn = (this.featureClassName =
             this.currentFeatureName =
                 pascalCase(feature.name) + 'Phrases');

package/dist/model/model.d.ts

@@ -121,12 +121,6 @@ export declare class Switch extends Part {
     toString(): string;
     toSingleLineString(): string;
 }
-export declare class Router extends Part {
-    choices: Repeater[];
-    constructor(choices: Repeater[]);
-    toString(): string;
-    toSingleLineString(): string;
-}
 export declare abstract class Arg extends Part {
     abstract toCode(cg: CodeGenerator): string;
     abstract toDeclaration(cg: CodeGenerator, index: number): string;

package/dist/model/model.js

@@ -210,12 +210,12 @@ export class Repeater extends Part {
         this.choices = choices;
     }
     toString() {
-        return `{${this.choices.map((ps) => ps.join(' ')).join(' & ')}}`;
+        return `{${this.choices.map((ps) => ps.join(' ')).join(' && ')}}`;
     }
     toSingleLineString() {
         return `{${this.choices
             .map((ps) => ps.map((p) => p.toSingleLineString()).join(' '))
-            .join(' & ')}}`;
+            .join(' && ')}}`;
     }
 }
 export class Switch extends Part {
@@ -224,22 +224,10 @@ export class Switch extends Part {
         this.choices = choices;
     }
     toString() {
-        return `{ ${this.choices.join(' / ')} }`;
+        return `{ ${this.choices.join('; ')} }`;
     }
     toSingleLineString() {
-        return `{ ${this.choices.map((c) => c.toSingleLineString()).join(' / ')} }`;
-    }
-}
-export class Router extends Part {
-    constructor(choices) {
-        super();
-        this.choices = choices;
-    }
-    toString() {
-        return `{ ${this.choices.join(' ; ')} }`;
-    }
-    toSingleLineString() {
-        return `{ ${this.choices.map((c) => c.toSingleLineString()).join(' ; ')} }`;
+        return `{ ${this.choices.map((c) => c.toSingleLineString()).join('; ')} }`;
     }
 }
 export class Arg extends Part {

package/dist/parser/lexer_rules.d.ts

@@ -13,8 +13,7 @@ export declare enum T {
     ClosingBracket = "]",
     OpeningBrace = "{",
     ClosingBrace = "}",
-    And = "&",
-    Slash = "/",
+    And = "&&",
     Semicolon = ";",
     DoubleQuoteString = "double-quote string",
     UnclosedDoubleQuoteString = "unclosed double-quote string",

package/dist/parser/lexer_rules.js

@@ -14,8 +14,7 @@ export var T;
     T["ClosingBracket"] = "]";
     T["OpeningBrace"] = "{";
     T["ClosingBrace"] = "}";
-    T["And"] = "&";
-    T["Slash"] = "/";
+    T["And"] = "&&";
     T["Semicolon"] = ";";
     T["DoubleQuoteString"] = "double-quote string";
     T["UnclosedDoubleQuoteString"] = "unclosed double-quote string";
@@ -46,8 +45,7 @@ const rules = [
     [true, /\]/y, T.ClosingBracket],
     [true, /\{/y, T.OpeningBrace],
     [true, /\}/y, T.ClosingBrace],
-    [true, /\//y, T.Slash],
-    [true, /&/y, T.And],
+    [true, /&&/y, T.And],
     [true, /;/y, T.Semicolon],
     [true, /!!/y, T.ErrorMark],
     [true, /=>/y, T.ResponseArrow],
@@ -69,6 +67,6 @@ const rules = [
     [true, /\$\{[^}\n]*/y, T.UnclosedVariable],
     [true, /\|(?: .*|(?=\n|$))/y, T.MultilineString],
     [true, /\|[^ \n]/y, T.InvalidMultilineStringMark],
-    [true, /.+?(?=[\[\]"`|#{}&/;]|\$\{|$|=>|!!|:\s*$)/my, T.Words],
+    [true, /.+?(?=[\[\]"`|#{};]|\$\{|$|=>|!!|&&|\/\/|:\s*$)/my, T.Words],
 ];
 export default rules;

package/dist/parser/parser.js

@@ -31,9 +31,7 @@ export const NEWLINES = list_sc(tok(T.Newline), nil()), WORDS = apply(tok(T.Word
 //list_sc(rep_sc(SIMPLE_PART), tok(T.And)),
 //(cs) => new Repeater(cs)
 //),
-SWITCH = apply(list_sc(SIMPLE_PART, tok(T.Slash)), (cs) => new Switch(cs)), 
-//ROUTER = apply(list_sc(REPEATER, tok(T.Semicolon)), (cs) => new Router(cs)),
-BRACES = kmid(tok(T.OpeningBrace), SWITCH, tok(T.ClosingBrace)), PART = alt_sc(SIMPLE_PART, BRACES), PHRASE = rep_sc(PART), ARG = alt_sc(DOUBLE_QUOTE_STRING, BACKTICK_STRING, DOCSTRING), SET_VARIABLE = apply(seq(VARIABLE, ARG), ([variable, value]) => new SetVariable(variable, value)), ACTION = alt_sc(SET_VARIABLE, apply(PHRASE, (parts, range) => new Action(parts).at(range))), RESPONSE = apply(seq(PHRASE, opt_sc(VARIABLE)), ([parts, variable], range) => new Response(parts, variable !== undefined ? new SaveToVariable(variable) : undefined).at(range)), ERROR_RESPONSE = apply(seq(ERROR_MARK, opt_sc(alt_sc(DOUBLE_QUOTE_STRING, DOCSTRING))), ([, parts]) => new ErrorResponse(parts)), SAVE_TO_VARIABLE = apply(VARIABLE, (variable) => new Response([], new SaveToVariable(variable))), ARROW = kright(opt_sc(NEWLINES), tok(T.ResponseArrow)), RESPONSE_ITEM = kright(ARROW, alt_sc(SAVE_TO_VARIABLE, ERROR_RESPONSE, RESPONSE)), STEP = apply(seq(ACTION, rep_sc(RESPONSE_ITEM)), ([action, responses]) => new Step(action, responses).setFork(true)), LABEL = apply(kleft(list_sc(PART, nil()), tok(T.Colon)), (words, range) => new Label(words.map((w) => w.toString()).join(' ')).at(range)), SECTION = apply(LABEL, (text) => new Section(text)), BRANCH = apply(alt_sc(SECTION, STEP), (branch, range) => branch.at(range)), // section first, to make sure there is no colon after step
+SWITCH = apply(list_sc(SIMPLE_PART, tok(T.Semicolon)), (cs) => new Switch(cs)), BRACES = kmid(tok(T.OpeningBrace), SWITCH, tok(T.ClosingBrace)), PART = alt_sc(SIMPLE_PART, BRACES), PHRASE = rep_sc(PART), ARG = alt_sc(DOUBLE_QUOTE_STRING, BACKTICK_STRING, DOCSTRING), SET_VARIABLE = apply(seq(VARIABLE, ARG), ([variable, value]) => new SetVariable(variable, value)), ACTION = alt_sc(SET_VARIABLE, apply(PHRASE, (parts, range) => new Action(parts).at(range))), RESPONSE = apply(seq(PHRASE, opt_sc(VARIABLE)), ([parts, variable], range) => new Response(parts, variable !== undefined ? new SaveToVariable(variable) : undefined).at(range)), ERROR_RESPONSE = apply(seq(ERROR_MARK, opt_sc(alt_sc(DOUBLE_QUOTE_STRING, DOCSTRING))), ([, parts]) => new ErrorResponse(parts)), SAVE_TO_VARIABLE = apply(VARIABLE, (variable) => new Response([], new SaveToVariable(variable))), ARROW = kright(opt_sc(NEWLINES), tok(T.ResponseArrow)), RESPONSE_ITEM = kright(ARROW, alt_sc(SAVE_TO_VARIABLE, ERROR_RESPONSE, RESPONSE)), STEP = apply(seq(ACTION, rep_sc(RESPONSE_ITEM)), ([action, responses]) => new Step(action, responses).setFork(true)), LABEL = apply(kleft(list_sc(PART, nil()), tok(T.Colon)), (words, range) => new Label(words.map((w) => w.toString()).join(' ')).at(range)), SECTION = apply(LABEL, (text) => new Section(text)), BRANCH = apply(alt_sc(SECTION, STEP), (branch, range) => branch.at(range)), // section first, to make sure there is no colon after step
 DENTS = apply(alt_sc(tok(T.Plus), tok(T.Minus)), (seqOrFork) => {
     return {
         dent: (seqOrFork.text.length - 2) / 2,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "harmonyc",
   "description": "Harmony Code - model-driven BDD for Vitest",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "author": "Bernát Kalló",
   "homepage": "https://github.com/harmony-ac/code#readme",
   "repository": {