harmonyc 0.20.0 → 0.21.0

package/AGENTS.md

@@ -0,0 +1,105 @@
+# Writing unit tests in .harmony files
+
+When writing unit tests, write them in `.harmony` files using a special structured format. This specification will be compiled to JS on-the-fly and imports the corresponding `.phrases.ts` files for step implementations.
+
+## File Structure
+
+For tests belonging to a feature, you need:
+
+- `example.harmony` - Test specifications (this file)
+- `example.phrases.ts` - Step implementations (you create this)
+
+## .harmony File Format
+
+### Syntax Rules
+
+#### Line start
+
+1. **Lines starting with `+ `** on the same level become forks, each creating a separate test case.
+2. **Lines starting with `- `** become consecutive test steps in the same test case
+3. Every other line is ignored
+
+#### Line content
+
+1. **Sections** are any line ending in `:`. It is ignored but is used for naming test cases and groups.
+2. **Steps** consist of an _action_ and an _expected outcome_ separated by `=>`.
+3. **Error steps** consist of an _action_ followed by `=> !!` and an _expected error message_ in double quotes.
+
+#### Action and Expected Outcome syntax
+
+Use human-readable phrases for both actions and expected outcomes.
+Both actions and expected outcomes can contain:
+
+- **words**
+- **punctuation** is ignored
+- **string arguments** enclosed in double quotes`"like this"`
+- **code arguments** enclosed in backticks `` `like this` ``
+
+Use string arguments for string parameters and code arguments for numbers, booleans, objects, arrays etc.
+
+If there is one obvious default action in the test case with one parameter, use an action that contains just that parameter.
+If there is one obvious default expected outcome with one parameter, use an expected outcome that contains just that parameter.
+
+### Example
+
+```harmony
+# Calculator Functions
+
+This library provides basic calculator functions.
+
++ multiply():
+  - multiply `2` and `3` => `6`
+  - multiply `-2` and `3` => `-6`
+
++ divide():
+  - divide `6` by `2` => `3`
+
+  Division by zero is an error.
+
+  + by zero:
+    We need to test both non-zero and zero dividends.
+    + divide `5` by `0` => !! "Division by zero"
+    + divide `0` by `0` => !! "Division by zero"
+```
+
+## .phrases.ts File Implementation
+
+Create a class that implements step methods corresponding to your test specifications. Use imports as needed, e.g. import the functions you are testing.
+
+`When_*` methods implement actions, and `Then_*` methods implement expected outcomes. `Then_*` methods receive
+an extra parameter, the return value of the preceding `When_*` method. Add the words and parameters from the action / expected outcome, separated by underscores, with parameters denoted by `X`,`Y`,`Z`,`A`,`B`,...
+
+Use vitest.expect in assertions.
+
+Error responses need no implementation.
+
+```typescript
+import { expect } from 'vitest'
+import { multiply, divide } from './calculator'
+
+export default class CalculatorPhrases {
+  result: number | undefined
+
+  async When_multiply_X_and_Y(a: number, b: number) {
+    return multiply(a, b)
+  }
+
+  async When_divide_X_by_Y(a: number, b: number) {
+    return divide(a, b)
+  }
+
+  async Then_X(expected: number, actual: number) {
+    expect(actual).toBe(expected)
+  }
+}
+```
+
+## Best Practices
+
+1. **Keep test descriptions clear and concise**
+2. **Group related tests using sections**
+3. **Use meaningful parameter names in method signatures, and add TypeScript types**
+4. **Store state in class properties for complex scenarios**
+5. **Handle edge cases explicitly (errors, null values, etc.)**
+6. **Use descriptive comments in-line to explain test groups**
+7. **Test both happy path and error conditions**

package/README.md

@@ -0,0 +1,142 @@
+# 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.
+
+## Setup
+
+You need to have Node.js installed. Then you can install Harmony Code in your project folder by:
+
+```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:
+
+```js
+import harmony from 'harmonyc/vitest'
+
+export default {
+  plugins: [harmony()],
+  include: ['src/**/*.harmony'],
+}
+```
+
+This will run .harmony files in vitest.
+
+## VSCode plugin
+
+Harmony Code has a [VSCode plugin](https://marketplace.visualstudio.com/items?itemName=harmony-ac.harmony-code) that supports syntax highlighting.
+
+Harmony Code is compatible with Vitest's VSCode plugin, so you can run and debug tests from the editor.
+
+## Syntax
+
+A `.harmony` file is a text file with a syntax that looks like this:
+
+```
++ 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`
+```
+
+### Indentation
+
+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
+
+`-` 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.
+
+### Phrases (actions and responses)
+
+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 `=>`.
+
+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.
+
+### Arguments
+
+Phrases (actions and responses) can have arguments which are passed to the implementation function. There are two types of arguments: strings and code fragments:
+
+```harmony
++ strings:
+  + hello "John"
++ code fragment:
+  + greet `3` times
+```
+
+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)
+})
+```
+
+### Labels
+
+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.
+
+### Comments
+
+Lines starting with `#` or `//` are comments and are ignored.
+
+### Switches
+
+You can generate multiple test cases by adding a `{ A / B / C }` syntax into action(s) and possibly response(s).
+
+```harmony
++ password is { "A" / "asdf" / "password123" } => !! "password is too weak"
+```
+
+### 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 `!!`.
+
+### Variables
+
+You can set variables in the tests and use them in strings and code fragments:
+
+```
++ set variable:
+  + ${name} "John"
+    + greet "${name}" => "hello John"
++ store result into variable:
+  + run process => ${result}
+    + "${result}" is "success"
+```
+
+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']});
+})
+```
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,16 @@
 {
   "name": "harmonyc",
-  "version": "0.20.0",
+  "description": "Harmony Code - model-driven BDD for Vitest",
+  "version": "0.21.0",
+  "author": "Bernát Kalló",
+  "homepage": "https://github.com/harmony-ac/code#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/harmony-ac/code.git"
+  },
+  "bugs": {
+    "url": "https://github.com/harmony-ac/code/issues"
+  },
   "type": "module",
   "scripts": {
     "build": "tsc",
@@ -9,11 +19,13 @@
     "test": "vitest --run",
     "test:compile": "tsx ./src/cli/cli 'src/**/*.harmony'",
     "dev": "vitest --watch",
-    "publish": "npm publish",
-    "release": "npm run build && release publish"
+    "publish": "cp ../../README.md . && npm publish",
+    "release": "npm run test && npm run build && release publish"
   },
   "files": [
-    "dist"
+    "dist",
+    "AGENTS.md",
+    "README.md"
   ],
   "exports": {
     "./vitest": {
@@ -42,5 +54,22 @@
     "typescript": "^5.3.3",
     "vite": "^7.1.10",
     "vitest": "^3.2.4"
-  }
+  },
+  "license": "MIT",
+  "keywords": [
+    "unit test",
+    "unit testing",
+    "bdd",
+    "behavior-driven",
+    "test design",
+    "test design automation",
+    "harmony.ac",
+    "test framework",
+    "model-based test",
+    "model-based testing",
+    "test model",
+    "test modeling",
+    "test modelling",
+    "vitest"
+  ]
 }