@step-forge/step-forge 0.0.5

package/.eslintignore

@@ -0,0 +1,6 @@
+.history
+.husky
+.vscode
+coverage
+dist
+node_modules

package/.eslintrc

@@ -0,0 +1,18 @@
+{
+  "root": true,
+  "parser": "@typescript-eslint/parser",
+  "plugins": ["@typescript-eslint", "prettier"],
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/eslint-recommended",
+    "plugin:@typescript-eslint/recommended",
+    "prettier"
+  ],
+  "env": {
+    "browser": true,
+    "node": true
+  },
+  "rules": {
+    "prettier/prettier": "error"
+  }
+}

package/.prettierignore

@@ -0,0 +1,6 @@
+.history
+.husky
+.vscode
+coverage
+dist
+node_modules

package/.prettierrc

@@ -0,0 +1,15 @@
+{
+  "printWidth": 80,
+  "tabWidth": 2,
+  "singleQuote": false,
+  "trailingComma": "es5",
+  "arrowParens": "avoid",
+  "bracketSpacing": true,
+  "useTabs": false,
+  "endOfLine": "auto",
+  "singleAttributePerLine": false,
+  "bracketSameLine": false,
+  "jsxSingleQuote": false,
+  "quoteProps": "as-needed",
+  "semi": true
+}

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Change Log
+
+All notable changes to the "@step-forge/step-forge" project will be documented in this file.
+
+## [0.0.5] - 2024-12-31
+
+- Add support for exporting steps
+
+## [0.0.4] - 2024-07-30
+
+- Update all packages to the latest versions
+- Remove support for CommonJS modules
+
+## [0.0.3] - 2024-01-23
+
+- Update all packages to the latest versions (update to vite 5.x)
+
+## [0.0.2] - 2023-01-18
+
+- Update all packages to the latest versions (update to vite 4.x)
+
+## [0.0.1] - 2022-09-08
+
+- Update all packages to the latest versions (update to vite 3.x)
+
+## [0.0.0] - 2022-03-28
+
+- Initial release

package/LICENSE.md

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2024 Justin Dragos
+
+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,289 @@
+# Step Forge
+
+Step Forge is a typed wrapper around the Cucumber library. It provides an opinionated way to define steps, work with scenario state, and enforce dependencies between steps.
+
+## Installation
+
+```bash
+npm install @step-forge/step-forge
+```
+
+
+## Getting Started
+### Setting Up World State
+
+```ts
+// features/steps/world.ts
+import { setWorldConstructor } from "@cucumber/cucumber";
+import { BasicWorld } from "@step-forge/step-forge";
+
+export interface GivenState {
+  user: string;
+}
+
+export interface WhenState {
+  name: string;
+}
+
+export interface ThenState {}
+
+setWorldConstructor(BasicWorld<GivenState, WhenState, ThenState>);
+```
+
+### Defining Steps
+
+This defines a `given` step that doesn't need input variables or dependencies.
+
+```ts
+// features/steps/common.ts
+import { givenBuilder } from "@step-forge/step-forge";
+
+type GivenState = {
+  user: string;
+};
+
+givenBuilder<GivenState>()
+  .statement("a user")
+  .step(() => {
+    return {
+      user: "John Doe",
+    };
+  })
+  .register();
+```
+
+This creates a cucumber step that conceptually looks like this:
+```ts
+Given("a user", function (this: World) {
+  this.given.merge({
+    user: "John Doe",
+  });
+});
+```
+
+Not very exciting if you are used to cucumber, but it gets better as this get more complex.
+
+#### Defining Steps with Statement Variables
+
+Let's create a similar step that takes the name as a variable instead of hardcoding it.
+
+```ts
+// features/steps/common.ts
+import { givenBuilder } from "@step-forge/step-forge";
+
+type GivenState = {
+  user: string;
+};
+
+givenBuilder<GivenState>()
+  .statement((userName: string) => `a user named ${userName}`)
+  .step(({ variables: [ userName ] }) => {
+    return {
+      user: userName,
+    };
+  })
+  .register();
+```
+
+Here you can see that you can pass a template function to the statement that will be used to generate the statement for the cucumber step. Additionally, the `variables` array is strongly typed to match the variables provided in the statement function.
+
+> Note: Right now only `string` variables are supported, but we're working to improve this.
+
+This creates a cucumber step that conceptually looks like this:
+```ts
+Given("a user named {name}", function (this: World, name: string) {
+  this.given.merge({
+    user: name,
+  });
+});
+```
+
+#### Defining Steps with Dependencies
+
+Now let's added other scenario dependencies to the step. Let's assume we have another step that sets the user's real name into context, and now we want to give them a user name in our step.
+
+```ts
+// features/steps/common.ts
+import { givenBuilder } from "@step-forge/step-forge";
+
+type GivenState = {
+  realName: string;
+  user: {
+    name: string;
+    realName: string;
+  }
+};
+
+givenBuilder<GivenState>()
+  .statement((userName: string) => `a user named ${userName}`)
+  // Since this is a given step, only allow dependencies on given state
+  // Strongly typed to ensure you can't depend on something not in given state
+  .dependencies({ given: { realName: "required"}})
+  .step(({ variables: [ userName ], given: { realName } }) => {
+    return {
+      user: {
+        name: userName,
+        // realName is of type `string` and is not possibly undefined since it was required
+        realName,
+      },
+    };
+  })
+  .register();
+```
+
+Now this is getting more interesting. We've added a dependency on the `realName` part of given state. Step Forge strongly types dependencies based on your world state, and properly restricts access based on the step type. Additionally, since `realName` is required Step Forge will fail the scenario if it doesn't exist when the step is run.
+
+This creates a cucumber step that conceptually looks like this:
+```ts
+Given("a user named {name}", function (this: World, name: string) {
+  if (!this.given.realName) {
+    fail("given.realName is required, but was not provided");
+  }
+  this.given.merge({
+    user: {
+      name,
+      realName: this.given.realName,
+    },
+  });
+});
+```
+
+#### Complex Dependencies
+
+Now let's add a `then` step to check that the user's realName matches what we expected in the given step.
+
+```gherkin
+# features/update-username.feature
+Feature: Updating a user's username
+
+  Scenario: Updating a user's username
+    Given a real name of "John Doe"
+    And a user name of "Furball"
+  When I update the username
+  Then the user's real name should not change
+```
+
+Now let's implement the `then` step.
+
+```ts
+// features/steps/common.ts
+import { thenBuilder } from "@step-forge/step-forge";
+
+type GivenState = {
+  realName: string;
+  user: {
+    name: string;
+    realName: string;
+  }
+}
+
+type WhenState = {
+  user: {
+    name: string;
+    realName: string;
+  }
+}
+
+type ThenState = {}
+
+thenBuilder<GivenState, WhenState, ThenState>()
+  .statement("the user's real name should not change")
+  .dependencies({
+    given: { realName: "required" },
+    when: { user: "required" }
+  })
+  .step(({ given: { realName: expectedRealName }, when: { user: updatedUser } }) => {
+    expect(updatedUser.realName).toEqual(expectedRealName);
+    // Then steps can return void if they are not adding anything to `then` state
+  })
+  .register();
+```
+
+Even though we have complex dependencies across multiple parts of state, Step Forge ensures that the dependencies are properly enforced. It also provides type safety ensuring that the step can't depend on something from state that isn't explicitly declared.
+
+
+### Simpler Step Definitions
+
+> Note: Defining steps this way currently doesn't work with the vs code extension. We're working to improve this.
+
+Some people find the builder syntax to be a bit verbose, having to provide the generics for `GivenState`, `WhenState`, and `ThenState`. If you prefer a simpler syntax you can export your own definitions that have some of it built in.
+
+```ts
+// features/steps/common.ts
+
+export const Given = givenBuilder<GivenState>().statement;
+export const When = whenBuilder<GivenState, WhenState>().statement;
+export const Then = thenBuilder<GivenState, WhenState, ThenState>().statement;
+```
+
+You can now define your steps like this:
+
+```ts
+// features/steps/user.ts
+import { Given } from "./common";
+
+// You can now start your definition with the statement directly, without having to provide GivenState or chain through the builder.
+Given("a user")
+.dependencies({ given: { realName: "required" } })
+.step(({ given: { realName } }) => {
+  return {
+    user: {
+      realName,
+    },
+  };
+})
+.register();
+```
+
+### Compile Time Gherkin Analysis
+
+> Note: These features are currently only available in the `@step-forge/step-forge-vscode`VS code extension.
+
+Hopefully you are excited about the strong typing and dependency enforcement that Step Forge provides. But there is more to it than just that. Since we each steps declares its dependencies, and we know what it sets in state from its `return` type, Step Forge can analyze your Gherkin scenarios and provide errors if there are unsatisfied dependencies.
+
+For instance, take the following steps and scenario:
+
+```ts
+// features/steps/user.ts
+import { Given } from "./common";
+
+type GivenState = {
+  name: string;
+  user: {
+    name: string;
+  }
+}
+
+Given((name: string) => `a user named ${name}`)
+.step(({ variables: [ name ] }) => {
+  return { name }
+})
+.register();
+
+When("I save the user")
+.dependencies({ given: { user: "required" } })
+.step(({ given: { user } }) => {
+  // save the user
+})
+.register();
+```
+
+```gherkin
+# features/update-username.feature
+Feature: Updating a user's username
+
+  Scenario: Updating a user's username
+    Given a user named "Furball"
+    # This step will show a compilation error because the given step sets "name", but the when step depends on "user"
+    When I save the user
+    Then the user's real name should not change
+```
+
+#### Autocomplete
+
+Additionally when adding a step to a feature file, if the step has unfulfilled dependencies, the extension will show a list of steps that can be used to fulfill the dependencies.
+
+![Step Forge Autocomplete Demo](./docs/assets/state_deps.gif)
+
+
+

package/cucumber.mjs

@@ -0,0 +1,38 @@
+const defaultProfile = {
+  format: [
+    process.env.CI || !process.stdout.isTTY ? "progress" : "progress-bar",
+    "json:./reports/cucumber-json-reports/report.json",
+    "rerun:./reports/cucumber/@rerun.txt",
+    "usage:./reports/cucumber/usage.txt",
+  ],
+  parallel: 1,
+  importModule: ["ts-node/esm", "tsconfig-paths/register"],
+  import: [
+    "./features/steps/**/*.ts",
+    "./features/steps/*.ts",
+    "./src/**/*.ts",
+  ],
+  strict: false,
+};
+
+const ciProfile = {
+  format: [
+    process.env.CI || !process.stdout.isTTY ? "progress" : "progress-bar",
+    "json:./reports/cucumber-json-reports/report.json",
+    "rerun:./reports/cucumber/@rerun.txt",
+    "usage:./reports/cucumber/usage.txt",
+  ],
+  parallel: 1,
+  importModule: ["ts-node/register/transpile-only", "tsconfig-paths/register"],
+  import: ["./features/steps/**/*.ts", "./features/steps/*.ts"],
+  strict: false,
+  publish: true,
+};
+
+const all = {
+  ...defaultProfile,
+  paths: ["./features"],
+};
+
+export { ciProfile as ci, all };
+export default defaultProfile;

package/dts-bundle-generator.config.ts

@@ -0,0 +1,11 @@
+const config = {
+  entries: [
+    {
+      filePath: "./src/index.ts",
+      outFile: "./build/dist/index.d.ts",
+      noCheck: false,
+    },
+  ],
+};
+
+module.exports = config;

package/features/basic.feature

@@ -0,0 +1,21 @@
+Feature: Steps written in gherkin can be matched to Step Forge steps
+
+    Scenario: Basic feature steps with no dependencies or variables can be run as a cucumber scenario
+        Given I started
+        When I got here
+        Then everything was good
+
+    Scenario: Basic feature steps with dependencies can be run as a cucumber scenario
+        Given a user
+        When I save the user
+        Then there is a user
+
+    Scenario: Basic feature steps with variables can be run as a cucumber scenario
+        Given a user named "John"
+        When I save the user
+        Then there is a user
+
+    Scenario: Basic feature steps with dependencies and variables can be run as a cucumber scenario
+        Given a user
+        When I name the user "John"
+        Then the user's name is "John"

package/features/exported.feature

@@ -0,0 +1,6 @@
+Feature: Builders can be re-exported for ease of use
+
+    Scenario: Exported steps can be used in cucumber scenarios
+        Given a bank user
+        When I deposit "1000" "USD"
+        Then the balance is "1000"

package/features/steps/commonSteps.ts

@@ -0,0 +1,93 @@
+import { givenBuilder } from "../../src/given";
+import { whenBuilder } from "../../src/when";
+import { thenBuilder } from "../../src/then";
+import { GivenState, ThenState, WhenState } from "./world";
+import { expect } from "earl";
+
+// --- No dependency no variable steps --- //
+givenBuilder<GivenState>()
+  .statement("I started")
+  .step(() => ({}))
+  .register();
+
+whenBuilder<GivenState, WhenState>()
+  .statement("I got here")
+  .step(() => ({}))
+  .register();
+
+thenBuilder<GivenState, WhenState, ThenState>()
+  .statement("everything was good")
+  .step(() => ({}))
+  .register();
+
+// --- Dependency only steps --- //
+givenBuilder<GivenState>()
+  .statement("a user")
+  .step(() => {
+    return {
+      user: {
+        type: "person",
+        token: "random",
+      },
+    };
+  })
+  .register();
+
+whenBuilder<GivenState, WhenState>()
+  .statement("I save the user")
+  .dependencies({ given: { user: "required" } })
+  .step(({ given: { user } }) => {
+    return {
+      user: {
+        ...user,
+        saved: true,
+      },
+    };
+  })
+  .register();
+
+thenBuilder<GivenState, WhenState, ThenState>()
+  .statement("there is a user")
+  .dependencies({ when: { user: "required" } })
+  .step(({ when: { user } }) => {
+    expect(user.saved).toBeTruthy();
+  })
+  .register();
+
+// --- Variable only steps --- //
+givenBuilder<GivenState>()
+  .statement((userName: string) => `a user named ${userName}`)
+  .step(({ variables: [userName] }) => {
+    return {
+      user: {
+        type: "person",
+        token: userName,
+      },
+    };
+  })
+  .register();
+
+// --- More complex steps --- //
+
+whenBuilder<GivenState, WhenState>()
+  .statement((userName: string) => `I name the user ${userName}`)
+  .dependencies({ given: { user: "required" } })
+  .step(({ given: { user }, variables: [userName] }) => {
+    return {
+      user: {
+        ...user,
+        token: userName,
+        saved: true,
+      },
+    };
+  })
+  .register();
+
+thenBuilder<GivenState, WhenState, ThenState>()
+  .statement((userName: string) => `the user's name is ${userName}`)
+  .dependencies({ when: { user: "required" } })
+  .step(({ when: { user }, variables: [userName] }) => {
+    const token = user.token;
+    expect(token).toEqual(userName);
+  })
+  .register();

package/features/steps/exportedSteps.ts

@@ -0,0 +1,42 @@
+import { expect } from "earl";
+import { givenBuilder } from "../../src/given";
+import { thenBuilder } from "../../src/then";
+import { whenBuilder } from "../../src/when";
+import { GivenState, ThenState, WhenState } from "./world";
+
+const Given = givenBuilder<GivenState>().statement;
+const When = whenBuilder<GivenState, WhenState>().statement;
+const Then = thenBuilder<GivenState, WhenState, ThenState>().statement;
+
+Given("a bank user")
+  .step(() => {
+    return {
+      user: {
+        type: "customer",
+        token: "random",
+      },
+    };
+  })
+  .register();
+
+When((amount: string, currency: string) => `I deposit ${amount} ${currency}`)
+  .dependencies({ given: { user: "required" } })
+  .step(({ variables: [rawAmount, currency], given: { user } }) => {
+    const amount = parseFloat(rawAmount);
+    return {
+      deposit: {
+        amount,
+        currency,
+        user,
+      },
+    };
+  })
+  .register();
+
+Then((amount: string) => `the balance is ${amount}`)
+  .dependencies({ when: { deposit: "required" } })
+  .step(({ when: { deposit }, variables: [rawAmount] }) => {
+    const amount = parseFloat(rawAmount);
+    expect(deposit.amount).toEqual(amount);
+  })
+  .register();

package/features/steps/world.ts

@@ -0,0 +1,29 @@
+import { setWorldConstructor } from "@cucumber/cucumber";
+import { BasicWorld } from "../../src/world";
+
+export interface GivenState {
+  user: {
+    type: string;
+    token: string;
+  };
+}
+
+export interface WhenState {
+  user: {
+    type: string;
+    token: string;
+    saved: boolean;
+  };
+  deposit: {
+    amount: number;
+    currency: string;
+    user: {
+      type: string;
+      token: string;
+    };
+  };
+}
+
+export interface ThenState {}
+
+setWorldConstructor(BasicWorld<GivenState, WhenState, ThenState>);

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@step-forge/step-forge",
+  "version": "0.0.5",
+  "module": "./dist/step-forge.js",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/step-forge.js"
+    },
+    "./dist/": {
+      "import": "./dist/"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "dev": "vite --host",
+    "build": "rimraf build/**/* && tsc && vite build && dts-bundle-generator --config ./dts-bundle-generator.config.ts && copyfiles ./package.json build",
+    "test:cucumber": "NODE_ENV=test NODE_OPTIONS=\"--experimental-specifier-resolution=node --loader ts-node/esm\" TS_NODE_PROJECT=./tsconfig.cucumber.json cucumber-js -p default",
+    "test:ci": "NODE_ENV=test cucumber-js -p ci",
+    "test": "NODE_ENV=test PORT=7888 LOG_LEVEL=none cucumber-js -p all 2> /dev/null",
+    "test:debug": "NODE_ENV=test PORT=7888 cucumber-js -p all",
+    "lint": "eslint . --ext .ts",
+    "format": "prettier . --write"
+  },
+  "devDependencies": {
+    "@cucumber/pretty-formatter": "^1.0.1",
+    "@types/jsdom": "^21.1.7",
+    "@types/lodash": "^4.17.13",
+    "@types/node": "^22.10.2",
+    "@typescript-eslint/eslint-plugin": "^7.18.0",
+    "@typescript-eslint/parser": "^7.18.0",
+    "@vitest/coverage-v8": "^2.0.4",
+    "copyfiles": "^2.4.1",
+    "dts-bundle-generator": "^9.5.1",
+    "earl": "^1.3.0",
+    "eslint": "^8.57.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-prettier": "^5.2.1",
+    "prettier": "^3.3.3",
+    "rimraf": "^6.0.1",
+    "ts-node": "^10.9.2",
+    "tsconfig-paths": "^4.2.0",
+    "typescript": "^5.7.2",
+    "vite": "^5.3.5",
+    "vitest": "^2.0.4"
+  },
+  "dependencies": {
+    "@cucumber/cucumber": "^11.1.1",
+    "lodash": "^4.17.21"
+  }
+}