@autometa/app 0.4.2 → 1.0.0-rc.0

package/dist/index.d.ts

@@ -1,110 +1,2 @@
-import { Container } from '@autometa/injection';
-import { Class } from '@autometa/types';
-
-/**
- * Basic Key Value store for managing state across Step Definitions. A unique copy of this object
- * is shared between all steps and hooks in a given running Scenario, however it is not possible
- * to interact with state outside of that Scenarios life cycle. That is to say, while the World
- * is shared between steps, it is unique across tests.
- *
- * To extend the worlds vocabulary, you can declare properties on the World. These do not need
- * to be defined at run time. Instead they will be filled in as they are produced by steps.
- *
- * To declare World properties, you can simply declare an uninitialized property. Depending
- * on your `tsconfig.json` settings you can do so with one of the three following syntaxes:
- *
- * ```typescript
- * @Fixture
- * export class World {
- *  [key: string]: unknown;
- *
- *  declare foo: number
- *
- *  foo: number
- *
- *  foo!: number
- * }
- *
- * The World is automatically injected into the {@link App} object, and can be accessed via
- * the last (or only) argument of a step definition callback.
- *
- * ```ts
- * Given('I have {int} cats', (cats: number, app: App) => {
- *    app.world.cats = cats
- * })
- *
- * // using destructuring
- * Given('I have {int} cats', ({world}: App) => {
- *   world.cats = cats
- * })
- * ```
- */
-interface World {
-    [key: string]: unknown;
-}
-/**
- * The App object is the primary interface for interacting with the running application. It is
- * composed of `Fixtures` which are classes decorated with the `@Fixture` decorator. Fixtures
- * are automatically instantiated and injected into the App object. The App object is then
- * injected into the last (or only) argument of a step definition callback.
- *
- * i.e.
- *
- * ```ts
- * // single argument
- * Given('I have 5 cats', (app: App) => {})
- * // Cucumber Expression
- * Given('I have {int} cats', (cats: number, app: App) => {})
- * // Data table
- * Given('I have {int} cats', (cats: number, table: HTable app: App) => {}, HTable)
- * ```
- *
- * **Note**: The type annotations here are optional. Non-custom Cucumber Expression types
- * will be automatically inferred by their expression template. Custom types will need to
- * be added via declaration file (see docs)
- *
- * The App is unique across all tests, and is shared between all steps and hooks within a test.
- * If you have any Fixture classes defined, you can add them as constructor parameters of the App
- * to make them available to step Definitions (Fixtures can also be accessed as properties from other Fixtures if not defined here);
- *
- * ```ts
- * \@\Fixture
- * export class World {}
- *
- *
- * \@\Fixture
- * export class Fixture1 {}
- *
- * \@\Fixture
- * export class Fixture2 {
- *  constructor(readonly fixture1: Fixture1, readonly world: World) {}
- * }
- *
- * \@\AppType(World)
- * export class App {
- *   constructor(readonly fixture1: Fixture1, readonly fixture2: Fixture2) {}
- * }
- * ```
- */
-interface App {
-    world: World;
-    di: Container;
-}
-
-declare abstract class AutometaApp {
-    id: string;
-    [key: string]: unknown;
-    world: World;
-}
-
-declare class AutometaWorld {
-}
-
-declare function getApp<T extends AutometaApp>(appType: Class<T>, containerName?: string): App;
-
-declare function AppType(container: Record<string, {
-    app: Class<App>;
-    world: Class<World>;
-}>, world: Class<AutometaWorld>, environment?: string): (target: Class<unknown>) => void;
-
-export { App, AppType, AutometaApp, AutometaWorld, World, getApp };
+export { createStepDefinitions } from "./create-step-definitions";
+export type { StepSuite, StepFactoryOptions, StepDsl, StepExpression, StepCallback, HookSuite, StepFlowBuilder, StepFlowRunner, WorldHierarchy, WorldScope, StepRuntimeContext, ScopeKeyResolver, } from "./types";

package/dist/index.js

@@ -1,71 +1,497 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+import { AutomationError } from '@autometa/errors';
+import { Container, Scope } from '@autometa/injection';
 
-// src/index.ts
-var src_exports = {};
-__export(src_exports, {
-  AppType: () => AppType,
-  AutometaApp: () => AutometaApp,
-  AutometaWorld: () => AutometaWorld,
-  getApp: () => getApp
-});
-module.exports = __toCommonJS(src_exports);
-
-// src/autometa-app.ts
-var AutometaApp = class {
-};
-
-// src/autometa-world.ts
-var AutometaWorld = class {
+// src/create-step-definitions.ts
+var ScopeManager = class {
+  constructor(options) {
+    this.options = options;
+    this.root = new Container();
+    this.enterHandlers = {
+      feature: /* @__PURE__ */ new Set(),
+      rule: /* @__PURE__ */ new Set(),
+      outline: /* @__PURE__ */ new Set(),
+      scenario: /* @__PURE__ */ new Set()
+    };
+    this.exitHandlers = {
+      feature: /* @__PURE__ */ new Set(),
+      rule: /* @__PURE__ */ new Set(),
+      outline: /* @__PURE__ */ new Set(),
+      scenario: /* @__PURE__ */ new Set()
+    };
+  }
+  getHierarchy() {
+    if (!this.scenario) {
+      throw new AutomationError("Scenario world has not been initialised yet.");
+    }
+    return {
+      scenario: this.scenario.instance,
+      feature: this.feature?.instance ?? void 0,
+      rule: this.rule?.instance ?? void 0,
+      outline: this.outline?.instance ?? void 0
+    };
+  }
+  async startScenario(rawContext, explicitKeys) {
+    const context = rawContext ?? {};
+    const keys = explicitKeys ?? this.resolveKeys(context);
+    await this.ensureFeature(keys, context);
+    await this.ensureRule(keys, context);
+    await this.ensureOutline(keys, context);
+    if (this.scenario) {
+      await this.disposeScenario(false);
+    }
+    this.scenario = this.createScopeState(
+      this.options.scenario,
+      keys.scenario,
+      this.parentContainerFor("scenario"),
+      context
+    );
+    this.syncHierarchyReferences();
+    await this.triggerEnter("scenario", context);
+  }
+  async finishScenario(context) {
+    await this.disposeScenario(true, context);
+  }
+  async resetAll(context) {
+    await this.disposeScenario(true, context);
+    await this.disposeOutline(context);
+    await this.disposeRule(context);
+    await this.disposeFeature(context);
+  }
+  onEnter(scope, handler) {
+    this.enterHandlers[scope].add(handler);
+  }
+  onExit(scope, handler) {
+    this.exitHandlers[scope].add(handler);
+  }
+  resolveKeys(context) {
+    const { keyResolver } = this.options;
+    const result = {
+      scenario: keyResolver.scenario(context)
+    };
+    const feature = keyResolver.feature?.(context);
+    if (feature) {
+      result.feature = feature;
+    }
+    const rule = keyResolver.rule?.(context);
+    if (rule) {
+      result.rule = rule;
+    }
+    const outline = keyResolver.outline?.(context);
+    if (outline) {
+      result.outline = outline;
+    }
+    if (!result.feature) {
+      result.feature = "feature";
+    }
+    return result;
+  }
+  hasScenario() {
+    return Boolean(this.scenario);
+  }
+  parentContainerFor(scope) {
+    switch (scope) {
+      case "feature":
+        return this.root;
+      case "rule":
+        return this.feature?.container ?? this.root;
+      case "outline":
+        return this.rule?.container ?? this.feature?.container ?? this.root;
+      case "scenario":
+      default:
+        return this.outline?.container ?? this.rule?.container ?? this.feature?.container ?? this.root;
+    }
+  }
+  ensureFeature(keys, context) {
+    const featureCtor = this.options.feature;
+    if (!featureCtor) {
+      return;
+    }
+    if (this.feature && this.feature.key === keys.feature) {
+      return;
+    }
+    return this.replaceFeature(featureCtor, keys.feature ?? "feature", context);
+  }
+  async ensureRule(keys, context) {
+    const ruleCtor = this.options.rule;
+    if (!ruleCtor) {
+      return;
+    }
+    if (this.rule && this.rule.key === keys.rule) {
+      return;
+    }
+    await this.disposeRule(context);
+    if (!keys.rule) {
+      return;
+    }
+    this.rule = this.createScopeState(
+      ruleCtor,
+      keys.rule,
+      this.parentContainerFor("rule"),
+      context
+    );
+    this.syncHierarchyReferences();
+    await this.triggerEnter("rule", context);
+  }
+  async ensureOutline(keys, context) {
+    const outlineCtor = this.options.outline;
+    if (!outlineCtor) {
+      return;
+    }
+    if (this.outline && this.outline.key === keys.outline) {
+      return;
+    }
+    await this.disposeOutline(context);
+    if (!keys.outline) {
+      return;
+    }
+    this.outline = this.createScopeState(
+      outlineCtor,
+      keys.outline,
+      this.parentContainerFor("outline"),
+      context
+    );
+    this.syncHierarchyReferences();
+    await this.triggerEnter("outline", context);
+  }
+  async replaceFeature(ctor, key, context) {
+    await this.disposeFeature(context);
+    this.feature = this.createScopeState(ctor, key, this.parentContainerFor("feature"), context);
+    this.syncHierarchyReferences();
+    await this.triggerEnter("feature", context);
+  }
+  createScopeState(ctor, key, parent, context) {
+    const container = parent.createChild();
+    container.registerClass(ctor, { scope: Scope.SINGLETON });
+    const instance = container.resolve(ctor);
+    return { ctor, key, container, instance, context };
+  }
+  async disposeScenario(runHandlers, context) {
+    if (!this.scenario) {
+      return;
+    }
+    if (runHandlers) {
+      await this.triggerExit("scenario", context ?? this.scenario.context);
+    }
+    await this.scenario.container.dispose();
+    this.scenario = void 0;
+  }
+  async disposeOutline(context) {
+    if (!this.outline) {
+      return;
+    }
+    await this.triggerExit("outline", context ?? this.outline.context);
+    await this.outline.container.dispose();
+    this.outline = void 0;
+  }
+  async disposeRule(context) {
+    if (!this.rule) {
+      return;
+    }
+    await this.triggerExit("rule", context ?? this.rule.context);
+    await this.rule.container.dispose();
+    this.rule = void 0;
+  }
+  async disposeFeature(context) {
+    if (!this.feature) {
+      return;
+    }
+    await this.triggerExit("feature", context ?? this.feature.context);
+    await this.feature.container.dispose();
+    this.feature = void 0;
+  }
+  async triggerEnter(scope, context) {
+    const handlers = this.enterHandlers[scope];
+    if (!handlers.size) {
+      return;
+    }
+    const payload = this.createPayload(scope);
+    for (const handler of handlers) {
+      await handler(payload, context);
+    }
+  }
+  async triggerExit(scope, context) {
+    const handlers = this.exitHandlers[scope];
+    if (!handlers.size) {
+      return;
+    }
+    const payload = this.createPayload(scope);
+    for (const handler of handlers) {
+      await handler(payload, context);
+    }
+  }
+  createPayload(scope) {
+    switch (scope) {
+      case "feature":
+        if (!this.feature) {
+          throw new AutomationError("Feature world has not been initialised.");
+        }
+        return { feature: this.feature.instance };
+      case "rule":
+        if (!this.rule) {
+          throw new AutomationError("Rule world has not been initialised.");
+        }
+        return {
+          feature: this.feature?.instance ?? void 0,
+          rule: this.rule.instance
+        };
+      case "outline":
+        if (!this.outline) {
+          throw new AutomationError("Outline world has not been initialised.");
+        }
+        return {
+          feature: this.feature?.instance ?? void 0,
+          rule: this.rule?.instance ?? void 0,
+          outline: this.outline.instance
+        };
+      case "scenario":
+      default:
+        if (!this.scenario) {
+          throw new AutomationError("Scenario world has not been initialised.");
+        }
+        return {
+          feature: this.feature?.instance ?? void 0,
+          rule: this.rule?.instance ?? void 0,
+          outline: this.outline?.instance ?? void 0,
+          scenario: this.scenario.instance
+        };
+    }
+  }
+  syncHierarchyReferences() {
+    if (this.rule?.instance && this.feature?.instance) {
+      this.attachParent(this.rule.instance, "feature", this.feature.instance);
+    }
+    if (this.outline?.instance) {
+      if (this.feature?.instance) {
+        this.attachParent(this.outline.instance, "feature", this.feature.instance);
+      }
+      if (this.rule?.instance) {
+        this.attachParent(this.outline.instance, "rule", this.rule.instance);
+      }
+    }
+    if (this.scenario?.instance) {
+      if (this.feature?.instance) {
+        this.attachParent(this.scenario.instance, "feature", this.feature.instance);
+      }
+      if (this.rule?.instance) {
+        this.attachParent(this.scenario.instance, "rule", this.rule.instance);
+      }
+      if (this.outline?.instance) {
+        this.attachParent(this.scenario.instance, "outline", this.outline.instance);
+      }
+    }
+  }
+  attachParent(target, property, value) {
+    if (property in target && Reflect.get(target, property) === value) {
+      return;
+    }
+    Object.defineProperty(target, property, {
+      value,
+      enumerable: false,
+      configurable: true,
+      writable: false
+    });
+  }
 };
 
-// src/get-app.ts
-var import_uuid = require("uuid");
-var import_injection = require("@autometa/injection");
-function getApp(appType, containerName = (0, import_uuid.v4)()) {
-  const context = (0, import_injection.defineContainerContext)(containerName);
-  const container = new import_injection.Container(context);
-  const app = container.get(appType);
-  app.di = container;
-  return app;
+// src/create-step-definitions.ts
+function baseCreateStepDefinitions(scenarioCtor, options = {}) {
+  const dsl = resolveDsl(options.dsl);
+  const keyResolver = options.keyResolver ?? defaultKeyResolver;
+  const manager = new ScopeManager({
+    scenario: scenarioCtor,
+    keyResolver,
+    ...options.feature ? { feature: options.feature } : {},
+    ...options.rule ? { rule: options.rule } : {},
+    ...options.outline ? { outline: options.outline } : {}
+  });
+  if (Array.isArray(options.expressions) && dsl.defineParameterType) {
+    for (const definition of options.expressions) {
+      dsl.defineParameterType(definition);
+    }
+  }
+  setupLifecycleHooks(dsl, manager);
+  const given = wrapStepRegistrar("Given", dsl, dsl.Given, manager);
+  const when = wrapStepRegistrar("When", dsl, dsl.When, manager);
+  const then = wrapStepRegistrar("Then", dsl, dsl.Then, manager);
+  const and = wrapStepRegistrar("And", dsl, dsl.And ?? dsl.Given, manager);
+  const but = wrapStepRegistrar("But", dsl, dsl.But ?? dsl.Given, manager);
+  const hooks = {
+    BeforeFeature(handler) {
+      manager.onEnter("feature", handler);
+    },
+    AfterFeature(handler) {
+      manager.onExit("feature", handler);
+    },
+    BeforeRule(handler) {
+      manager.onEnter("rule", handler);
+    },
+    AfterRule(handler) {
+      manager.onExit("rule", handler);
+    },
+    BeforeOutline(handler) {
+      manager.onEnter("outline", handler);
+    },
+    AfterOutline(handler) {
+      manager.onExit("outline", handler);
+    },
+    BeforeScenario(handler) {
+      manager.onEnter("scenario", handler);
+    },
+    AfterScenario(handler) {
+      manager.onExit("scenario", handler);
+    }
+  };
+  const flow = createFlowBuilder({
+    given,
+    when,
+    then,
+    and,
+    but
+  });
+  return {
+    Given: given,
+    When: when,
+    Then: then,
+    And: and,
+    But: but,
+    hooks,
+    flow
+  };
 }
-
-// src/decorators/app-type.ts
-var import_injection2 = require("@autometa/injection");
-function AppType(container, world, environment = "default") {
-  const env = environment ?? "default";
-  return (target) => {
-    (0, import_injection2.metadata)(target).set({
-      key: "world",
-      class: world
-    });
-    container[env] = {
-      app: target,
-      world
+var createStepDefinitions = Object.assign(
+  baseCreateStepDefinitions,
+  {
+    flow: (scenarioCtor, options) => baseCreateStepDefinitions(scenarioCtor, options).flow
+  }
+);
+function resolveDsl(dsl) {
+  if (!dsl) {
+    throw new AutomationError(
+      "Step-definition DSL is required. Pass an explicit dsl option when creating step definitions."
+    );
+  }
+  return ensureRegistrars(dsl);
+}
+function ensureRegistrars(dsl) {
+  if (!dsl.Given || !dsl.When || !dsl.Then) {
+    throw new AutomationError("Step DSL must provide Given, When, and Then registrars.");
+  }
+  return dsl;
+}
+function wrapStepRegistrar(keyword, dsl, registrar, manager) {
+  if (!registrar) {
+    return () => {
+      throw new AutomationError(`Step DSL does not expose a registrar for ${keyword}.`);
     };
+  }
+  return (expression, handler) => {
+    const wrapped = createStepWrapper(keyword, expression, handler, manager);
+    registrar.call(dsl, expression, wrapped);
+  };
+}
+function createStepWrapper(keyword, expression, handler, manager) {
+  return async function stepExecution(...args) {
+    if (!manager.hasScenario()) {
+      const context = resolveRuntimeContext(void 0, this);
+      const keys = manager.resolveKeys(context);
+      await manager.startScenario(context, keys);
+    }
+    const { scenario } = manager.getHierarchy();
+    try {
+      if (expectsThis(handler)) {
+        return await handler.apply(scenario, args);
+      }
+      return await handler(scenario, ...args);
+    } catch (error) {
+      throw wrapStepError(error, keyword, expression);
+    }
+  };
+}
+function expectsThis(handler) {
+  return Boolean(handler.prototype);
+}
+function wrapStepError(error, keyword, expression) {
+  if (error instanceof AutomationError) {
+    return error;
+  }
+  const baseMessage = error instanceof Error ? error.message : typeof error === "string" ? error : "Unknown error";
+  const message = `Step failed for ${keyword} ${String(expression)}: ${baseMessage}`;
+  return new AutomationError(message, {
+    cause: error instanceof Error ? error : void 0
+  });
+}
+function resolveRuntimeContext(hookArg, worldValue) {
+  if (hookArg && typeof hookArg === "object") {
+    return hookArg;
+  }
+  if (worldValue && typeof worldValue === "object") {
+    return worldValue;
+  }
+  return {};
+}
+function setupLifecycleHooks(dsl, manager) {
+  if (dsl.Before) {
+    dsl.Before.call(dsl, async function beforeScenario(context) {
+      const runtime = resolveRuntimeContext(context, this);
+      await manager.startScenario(runtime);
+    });
+  }
+  if (dsl.After) {
+    dsl.After.call(dsl, async function afterScenario(context) {
+      const runtime = resolveRuntimeContext(context, this);
+      await manager.finishScenario(runtime);
+    });
+  }
+  if (dsl.AfterAll) {
+    dsl.AfterAll.call(dsl, async function afterAll() {
+      const runtime = resolveRuntimeContext(void 0, this);
+      await manager.resetAll(runtime);
+    });
+  }
+}
+function createFlowBuilder(registrars) {
+  const builder = {
+    given: (expression) => createFlowRunner(registrars.given, expression, () => builder),
+    when: (expression) => createFlowRunner(registrars.when, expression, () => builder),
+    then: (expression) => createFlowRunner(registrars.then, expression, () => builder),
+    and: (expression) => createFlowRunner(registrars.and, expression, () => builder),
+    but: (expression) => createFlowRunner(registrars.but, expression, () => builder)
+  };
+  return builder;
+}
+function createFlowRunner(registrar, expression, next) {
+  return {
+    run(handler) {
+      registrar(expression, handler);
+      return next();
+    }
   };
 }
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  AppType,
-  AutometaApp,
-  AutometaWorld,
-  getApp
-});
+var nextScenarioId = createKeyFactory("scenario");
+var defaultKeyResolver = {
+  feature(context) {
+    return context.gherkinDocument?.feature?.name ?? context.pickle?.uri ?? void 0;
+  },
+  rule(context) {
+    const nodes = context.pickle?.astNodeIds;
+    return Array.isArray(nodes) && nodes.length > 1 ? nodes[0] : void 0;
+  },
+  outline(context) {
+    const nodes = context.pickle?.astNodeIds;
+    if (Array.isArray(nodes) && nodes.length > 1) {
+      return nodes.slice(1).join(":");
+    }
+    return void 0;
+  },
+  scenario(context) {
+    return context.pickle?.id ?? context.pickle?.name ?? nextScenarioId();
+  }
+};
+function createKeyFactory(prefix) {
+  let counter = 0;
+  return () => `${prefix}-${++counter}`;
+}
+
+export { createStepDefinitions };
+//# sourceMappingURL=out.js.map
 //# sourceMappingURL=index.js.map