@g_package/jest-cucumber-fusion 2.0.0 → 3.0.0

package/src/feature-source.js

@@ -0,0 +1,322 @@
+// Driven port: everything outside the process boundary that getting a feature file needs.
+//
+// This is the ONLY module under src/ that requires the filesystem, the Gherkin parser or the
+// caller-stack reader: docs/Architecture.md's table says so, and
+// test/specs/arch/dependency-direction.steps.js holds every module to its row. It hands the
+// rest of the package one plain value (a LoadedFeature), so the core works on values and
+// needs no file or parser to be read or tested.
+//
+// LoadedFeature, the whole of what crosses back:
+//   { title, featureTags, scenarios: [ { title, excludedByTagFilter, tags,
+//                                        steps: [ { keyword, stepText, stepArgument } ] } ] }
+// `keyword` is already a registry bucket, `stepText` is already substituted for its Examples
+// row, and `stepArgument` is already the shape a step function receives, so nothing
+// downstream has to know a pickle exists. `excludedByTagFilter` is present only when a
+// tagFilter was given, and `featureTags` and `tags` are read only when a scenarioNameTemplate
+// is given; all three are read by presence or truthiness, so a value staged without them
+// behaves exactly as one did before those options did anything.
+
+import fs from "fs";
+import path from "path";
+import url from "url";
+import callerSites from "callsites";
+import * as gherkin from "@cucumber/gherkin";
+import * as messages from "@cucumber/messages";
+// The named export, not the default: 11.0.1 publishes both, and `default` is interop
+// scaffolding a later major could drop without that being a documented breaking change.
+import { parse as parseTagExpression } from "@cucumber/tag-expressions";
+
+import { bucketForKeyword } from "./keywords.js";
+import { stepArgumentFrom } from "./step-argument.js";
+import { tagFilterFor } from "./tag-filter.js";
+
+// Resolve the feature path from the FIRST stack frame outside this package, so an in-package
+// re-export/wrapper frame does not retarget it; guard a shallow stack (no external frame) so
+// we never call getFileName() on undefined.
+//
+// Only a frame whose file is ON DISK can be the caller: an absolute path, or the file: URL an
+// ES module frame reports. Any other frame is skipped: a native function holds one with no file
+// name when Fusion is handed straight to it, `[...].forEach(Fusion)`; Node's own modules report
+// `node:events` and the like; code run through vm reports `evalmachine.<anonymous>`. Taking any
+// of them as the caller resolved the path against the working directory (finding F7 of the
+// PR #16 review, and the review of its fix).
+const fileOnDisk = (fileName) => {
+  if (typeof fileName !== "string") return null;
+  if (fileName.startsWith("file:")) return url.fileURLToPath(fileName);
+  return path.isAbsolute(fileName) ? fileName : null;
+};
+
+// The directory this module runs from: src/ for the ES module entry, dist/ for the CommonJS
+// bundle, where scripts/build-cjs.js defines import.meta.url as the bundle's own file.
+const THIS_PACKAGE_DIRECTORY = path.dirname(url.fileURLToPath(import.meta.url));
+
+const resolveFeaturePath = (featureFileToLoad) => {
+  const insideThisPackage = (fileName) =>
+    fileName.startsWith(THIS_PACKAGE_DIRECTORY + path.sep);
+
+  const callerFile = callerSites()
+    .map((currentFrame) => fileOnDisk(currentFrame.getFileName()))
+    .find((fileName) => fileName !== null && !insideThisPackage(fileName));
+  const dirOfCaller = path.dirname(callerFile || "");
+
+  return path.resolve(dirOfCaller, featureFileToLoad);
+};
+
+const readFeatureText = (absoluteFeatureFilePath) => {
+  if (!fs.existsSync(absoluteFeatureFilePath))
+    throw new Error(
+      `Feature file not found (${absoluteFeatureFilePath})` +
+        `. Fusion resolves a feature path relative to the directory of the file that calls` +
+        ` Fusion, so check the path from there.`,
+    );
+
+  // A directory exists too, and reading it threw a raw EISDIR (fresh fuzz of PR #16).
+  if (fs.statSync(absoluteFeatureFilePath).isDirectory())
+    throw new Error(
+      `Feature path is a directory, not a feature file (${absoluteFeatureFilePath})` +
+        `. Name the .feature file itself, relative to the file that calls Fusion.`,
+    );
+
+  return fs.readFileSync(absoluteFeatureFilePath, "utf8");
+};
+
+// Parsing and compiling are two steps rather than one so that a check over the parsed AST
+// (the duplicate declared-title check below) can refuse before any pickle work is done.
+const parseFeature = (featureText) => {
+  // One incrementing id source, shared with the compile below: it replaces the uuid v4 the
+  // removed intermediary used, which is one of the two routes by which uuid reached a
+  // consumer's tree.
+  const ids = messages.IdGenerator.incrementing();
+  const parser = new gherkin.Parser(
+    new gherkin.AstBuilder(ids),
+    new gherkin.GherkinClassicTokenMatcher(),
+  );
+
+  try {
+    return { document: parser.parse(featureText), ids };
+  } catch (parseFailure) {
+    throw new Error(`Error parsing feature Gherkin: ${parseFailure.message}`);
+  }
+};
+
+const compilePickles = (document, absoluteFeatureFilePath, ids) => {
+  try {
+    return gherkin.compile(document, absoluteFeatureFilePath, ids);
+  } catch (compileFailure) {
+    throw new Error(`Error parsing feature Gherkin: ${compileFailure.message}`);
+  }
+};
+
+// Every child of a feature, in document order, with a Rule's own children flattened in where
+// the Rule is declared. One walker for both views below, so a Rule-nesting fix is made once
+// rather than twice in two copies that have to be kept agreeing.
+//
+// A rule child is visited as well as descended into, not instead: that is what the two copies
+// did, and the traversal has to stay equivalent because the registration order read off it is
+// the 2.0.0 test-name contract.
+const eachChild = (children, visit) => {
+  (children || []).forEach((child) => {
+    if (child.rule) eachChild(child.rule.children, visit);
+    visit(child);
+  });
+};
+
+// Every AST step, by id, so a pickle step can be resolved back to the keyword a consumer
+// registered against. A Rule's Background and scenarios carry steps of their own, which is why
+// the walk descends.
+const astStepsById = (feature) => {
+  const steps = new Map();
+
+  eachChild(feature.children, (child) => {
+    const node = child.background || child.scenario;
+    if (node) node.steps.forEach((step) => steps.set(step.id, step));
+  });
+
+  return steps;
+};
+
+// Every AST scenario, in document order, Rule children flattened in where they are declared.
+// This is the DEFINITION-level view of the feature, and the only one anywhere in the package:
+// one entry per declared Scenario or Scenario Outline, whatever its Examples do. Both the
+// registration order and the duplicate-title check are read off it.
+const astScenarios = (feature) => {
+  const scenarios = [];
+
+  eachChild(feature.children, (child) => {
+    if (child.scenario) scenarios.push(child.scenario);
+  });
+
+  return scenarios;
+};
+
+const byId = (scenarios) =>
+  new Map(scenarios.map((scenario) => [scenario.id, scenario]));
+
+// Titles declared more than once, in the order they are first declared, each with its count.
+// Compared case-insensitively, as the removed intermediary compared them
+// (scenario-validation.js:8 and :14-17).
+//
+// DECLARED titles, never generated test names. One Scenario Outline contributes exactly one
+// title however many Examples rows it has, which is the whole correctness of this check: a
+// check over generated names would reject test/specs/features/scenario-outlines.feature,
+// whose single outline produces three tests all named "Selling all of one", three names the
+// 2.0.0 baseline records.
+const duplicatedTitles = (scenarios) => {
+  const countByComparableTitle = new Map();
+
+  scenarios.forEach((scenario) => {
+    const comparable = scenario.name.trim().toLowerCase();
+    const seen = countByComparableTitle.get(comparable);
+
+    if (seen) seen.count += 1;
+    else
+      countByComparableTitle.set(comparable, {
+        title: scenario.name,
+        count: 1,
+      });
+  });
+
+  return [...countByComparableTitle.values()].filter((each) => each.count > 1);
+};
+
+const refuseDuplicatedTitles = (featureTitle, duplicated) => {
+  const entries = duplicated.map(
+    (each, index) =>
+      `  ${index + 1}. "${each.title}" is declared ${each.count} times`,
+  );
+
+  throw new Error(
+    `Duplicate scenario title: ${duplicated.length} title${
+      duplicated.length === 1 ? " is" : "s are"
+    } declared more than once in the feature "${featureTitle}".\n\n` +
+      `${entries.join("\n")}\n\n` +
+      `WHY:  Fusion generates one test per scenario, named for that scenario, so two\n` +
+      `      scenarios declared with the same title cannot be told apart in a Jest report,\n` +
+      `      by a -t filter, or in a test history. Titles are compared ignoring case, and a\n` +
+      `      scenario inside a Rule counts with the rest.\n` +
+      `HOW:  rename one of each pair, or pass\n` +
+      `      errors: { scenariosMustMatchFeatureFile: false } to accept the file as it\n` +
+      `      stands. A Scenario Outline counts once however many Examples rows it has, so\n` +
+      `      repeated ROW names are never this refusal.`,
+  );
+};
+
+// The first of a pickle node's astNodeIds that names something in the given index wins. A
+// pickle step carries the ids of every AST node it was compiled from, and a pickle carries its
+// scenario's and, on an Examples row, that row's: only some of them are in any one index.
+const firstAstNodeOf = (pickleNode, byAstNodeId) =>
+  (pickleNode.astNodeIds || [])
+    .map((astNodeId) => byAstNodeId.get(astNodeId))
+    .find((candidate) => candidate !== undefined);
+
+const keywordOfPickleStep = (pickleStep, stepsById, language) => {
+  const astStep = firstAstNodeOf(pickleStep, stepsById);
+
+  if (!astStep)
+    throw new Error(
+      `Unresolvable step: "${pickleStep.text}" carries no astNodeId that names a step of` +
+        ` the parsed feature, so the Gherkin keyword it was written with cannot be` +
+        ` recovered and Fusion cannot tell which step definitions may bind it.`,
+    );
+
+  return bucketForKeyword(
+    astStep.keyword,
+    gherkin.dialects[language],
+    language,
+  );
+};
+
+// Reproduce the registration order the previous engine produced: within one feature, EVERY
+// plain scenario comes before ANY Examples row, each group in document order. Compiling
+// pickles yields document order, so this partition is the whole of the difference, and a
+// consumer's CI history is keyed on it (test/specs/baseline/test-names-2.0.0.txt).
+//
+// Rule-nested scenarios and outlines take part in the same two groups, flattened: the
+// previous engine read one flat scenario list and one flat outline list for the whole
+// feature, with no Rule in between.
+const PLAIN_SCENARIOS_FIRST = 0;
+const EXAMPLES_ROWS_AFTER = 1;
+
+const scenarioOrder = (pickle, scenariosById) => {
+  const astScenario = firstAstNodeOf(pickle, scenariosById);
+
+  return astScenario && (astScenario.examples || []).length > 0
+    ? EXAMPLES_ROWS_AFTER
+    : PLAIN_SCENARIOS_FIRST;
+};
+
+const inRegistrationOrder = (pickles, scenariosById) =>
+  [PLAIN_SCENARIOS_FIRST, EXAMPLES_ROWS_AFTER].flatMap((group) =>
+    pickles.filter((pickle) => scenarioOrder(pickle, scenariosById) === group),
+  );
+
+// The tag set a filter is evaluated against is the compiled pickle's own, which already unions
+// the scenario's tags, the feature's tags and, for an Examples row, that Examples set's tags.
+// One source makes that union correct by construction; the previous engine assembled it by
+// hand in two places and had to keep them agreeing.
+// The same shape reads a feature node's own declared tags, which is the other list a
+// scenarioNameTemplate is handed. One reader of the tag shape rather than two.
+const tagNamesOf = (tagged) => (tagged.tags || []).map((tag) => tag.name);
+
+// No tagFilter means no filter is constructed and no scenario is marked, so loading is
+// byte-for-byte what it was before this option did anything.
+const tagFilterFrom = (options) =>
+  options.tagFilter
+    ? tagFilterFor(options.tagFilter, parseTagExpression)
+    : null;
+
+// `options` is the merged configuration, which always carries a complete three-key errors
+// object. Two keys govern this port: scenariosMustMatchFeatureFile for the duplicate check,
+// and tagFilter for the selection.
+const loadFeature = (absoluteFeatureFilePath, options) => {
+  const featureText = readFeatureText(absoluteFeatureFilePath);
+  const { document, ids } = parseFeature(featureText);
+
+  const feature = document.feature;
+  if (!feature) return { title: "", scenarios: [] };
+
+  const scenarios = astScenarios(feature);
+
+  // Refused before the pickles are compiled: nothing downstream can make sense of a feature
+  // whose scenarios cannot be told apart, so the work is not worth doing. It stays ahead of
+  // the tags deliberately: a duplicated title is a property of the FILE, so a selection must
+  // never be able to make a duplicate-title file acceptable.
+  if (options.errors.scenariosMustMatchFeatureFile) {
+    const duplicated = duplicatedTitles(scenarios);
+    if (duplicated.length > 0) refuseDuplicatedTitles(feature.name, duplicated);
+  }
+
+  // Parsed before the pickles too, so an unreadable expression is a refusal that costs the
+  // consumer nothing else and reaches them before anything is registered.
+  const selects = tagFilterFrom(options);
+
+  const pickles = compilePickles(document, absoluteFeatureFilePath, ids);
+  const stepsById = astStepsById(feature);
+  const scenariosById = byId(scenarios);
+
+  return {
+    title: feature.name,
+    // The feature's own declared tags, kept apart from the scenarios'. Only a
+    // scenarioNameTemplate reads them, and it needs the two lists separately.
+    featureTags: tagNamesOf(feature),
+    scenarios: inRegistrationOrder(pickles, scenariosById).map((pickle) => ({
+      title: pickle.name,
+      // Marked, never dropped: a scenario a filter excludes still has to appear in the report
+      // under its own name, or a tag filter is indistinguishable from deleting a scenario.
+      excludedByTagFilter: selects ? !selects(tagNamesOf(pickle)) : false,
+      // The whole tag set that reached this scenario, as the pickle unions it. The core
+      // subtracts the feature's tags from it where the template variables are assembled; the
+      // case is left exactly as the feature file wrote it, because only that assembly wants it
+      // lowercased.
+      tags: tagNamesOf(pickle),
+      steps: pickle.steps.map((pickleStep) => ({
+        keyword: keywordOfPickleStep(pickleStep, stepsById, feature.language),
+        stepText: pickleStep.text,
+        stepArgument: stepArgumentFrom(pickleStep.argument),
+      })),
+    })),
+  };
+};
+
+export { resolveFeaturePath };
+export { loadFeature };

package/src/index.d.ts

@@ -1,14 +1,17 @@
-// Type definitions for jest-cucumber-fusion 0.6
-// Project: https://github.com/b-yond-infinite-network/jest-cucumber-fusion#readme
-// Definitions by: Pelle Johnsen <https://github.com/pjoe>
-// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
-// Minimum TypeScript Version: 3.4
+// Type definitions for @g_package/jest-cucumber-fusion
+// Project: https://github.com/gotreasa/jest-cucumber-fusion#readme
+// Originally written by Pelle Johnsen <https://github.com/pjoe> for DefinitelyTyped.
 
-import { loadFeature } from "jest-cucumber";
+/** What Fusion passes a step: a capture or a docstring as a string, a data table as its rows. */
+export type StepArgument = string | Array<Record<string, string>>;
 
-export type CallBack = (
-  ...args: ReadonlyArray<string | Array<Record<string, string>>>
-) => void | Promise<void>;
+// Declared through a method so its parameters are checked bivariantly: a step may declare
+// the narrower type it receives, such as `(count: string) => ...`, which a plain function type
+// refuses under strictFunctionTypes. A type Fusion never passes, such as `number`, is still
+// refused, and an undeclared parameter is still a StepArgument.
+export type CallBack = {
+  step(...args: ReadonlyArray<StepArgument>): void | Promise<void>;
+}["step"];
 
 export interface StepChain {
   stepSentence: string | RegExp;
@@ -29,7 +32,114 @@ export function But(chain: StepChain): StepChain;
 export function Before(callback: () => void | Promise<void>): void;
 export function After(callback: () => void | Promise<void>): void;
 
-export function Fusion(
-  feature: string,
-  options?: Parameters<typeof loadFeature>[1]
-): void;
+/**
+ * Which of Fusion's validations are on.
+ *
+ * - `stepsMustMatchFeatureFile` (default on): a feature step that no registered definition
+ *   matches is refused at collection, in one message naming every unbound step of the feature
+ *   with starter code for each. Off, the scenarios holding those steps are registered through
+ *   `test.skip`, so Jest reports them as skipped and never as passed.
+ * - `scenariosMustMatchFeatureFile` (default on): two scenarios of one feature file declared
+ *   with the same title, ignoring case and counting a scenario inside a Rule, are refused at
+ *   collection. A Scenario Outline counts once however many Examples rows it has, so repeated
+ *   row names are never a duplicate. Off, the file is accepted as written.
+ * - `allowScenariosNotInFeatureFile`: accepted and vestigial. Fusion generates the scenario
+ *   definitions from the feature file itself, so there is no scenario outside it to allow.
+ *
+ * As a boolean, `errors` is shorthand: `true` turns every key on, `false` turns every key off.
+ * As an object it merges KEY-WISE over the defaults, so naming one key says nothing about the
+ * others. Switching the step check off leaves the duplicate check exactly as it was.
+ */
+export interface FusionErrorOptions {
+  stepsMustMatchFeatureFile?: boolean;
+  scenariosMustMatchFeatureFile?: boolean;
+  allowScenariosNotInFeatureFile?: boolean;
+}
+
+/**
+ * What a scenarioNameTemplate is handed, once per test. Unchanged from the shape consumers
+ * already write: these four variables and no others.
+ *
+ * `scenarioTitle` is the title of the individual test being named. For a Scenario Outline row
+ * that is the row's OWN substituted title, so each row gets its own name.
+ *
+ * `featureTags` are the feature's declared tags. `scenarioTags` are the rest of the tags that
+ * reached the scenario, which for an Examples row includes that Examples set's tags. The two
+ * lists are disjoint, and every tag carries its leading `@` and is lowercased. A tag declared
+ * on both the feature and the scenario appears in `featureTags` only.
+ */
+export interface ScenarioNameTemplateVars {
+  featureTitle: string;
+  scenarioTitle: string;
+  scenarioTags: string[];
+  featureTags: string[];
+}
+
+export interface FusionOptions {
+  /**
+   * Accepted and ignored. Fusion always resolves a relative feature path against the
+   * directory of the file that called it, and hands an absolute path on from there, so there
+   * is nothing left for this to switch.
+   */
+  loadRelativePath?: boolean;
+  errors?: boolean | FusionErrorOptions;
+  /**
+   * Which scenarios to run, as a tag expression: a tag name written `@name`, combined with
+   * the operators `and`, `or` and `not` and grouped with parentheses. For example
+   * `@smoke and not @slow`, or `@shop and (@included or @draft)`.
+   *
+   * Matching ignores case on both sides: the expression and every tag are lowercased before
+   * they are compared, so the operators may be written in any case too.
+   *
+   * A scenario is selected on the tags its compiled pickle carries, which is the union of the
+   * scenario's own tags, its feature's tags and, for a Scenario Outline row, that Examples
+   * set's tags. A scenario the expression excludes is registered through `test.skip` under its
+   * own unannotated name, so Jest reports it as skipped: never run, and never absent from the
+   * report. Its steps are also exempt from the unmatched-step check, because a scenario you
+   * excluded is not one you are asking to have wired. They are still read, so a step with an
+   * unsupported keyword (`*`) or one that matches two definitions is refused all the same.
+   *
+   * An expression that cannot be parsed is refused at collection, before anything is
+   * registered, and the refusal names the expression you wrote. So is one with an operand
+   * that is not a tag, such as `smoke` written for `@smoke`: it could never match.
+   */
+  tagFilter?: string;
+  /**
+   * Renames every test Fusion registers, Scenario Outline rows included. It is called once per
+   * test while Fusion registers, never again while the tests run, and it names a test whatever
+   * its status: a scenario skipped because a tag filter excluded it, or because its steps do
+   * not bind, carries the same templated name it would have carried had it run.
+   *
+   * It must return a non-empty string. A template that throws, or that answers with anything
+   * else, is refused at collection rather than naming a test something Jest cannot report.
+   */
+  scenarioNameTemplate?: (vars: ScenarioNameTemplateVars) => string;
+}
+
+export function Fusion(feature: string, options?: FusionOptions): void;
+
+/**
+ * Sets options for every `Fusion()` call in the current test file, so they need not be repeated
+ * in each one. Meant for a script listed in Jest's `setupFiles`:
+ *
+ * ```js
+ * // jest.config.js      ->  setupFiles: ["<rootDir>/jest.setup.js"]
+ * // jest.setup.js
+ * const { setFusionConfiguration } = require("@g_package/jest-cucumber-fusion");
+ * setFusionConfiguration({ tagFilter: "@smoke and not @slow" });
+ * ```
+ *
+ * Options are merged lowest to highest: the defaults, then whatever this setter holds, then the
+ * options passed to one `Fusion()` call. A per-call option therefore still wins for its own
+ * file, and `errors` merges key-wise at every layer, so naming one validation never switches
+ * off another. An option set to `undefined`, such as an unset environment variable forwarded
+ * as `{ tagFilter: process.env.TAGS }`, counts as not set and leaves the layer below in place.
+ *
+ * A second call REPLACES what the first set rather than merging into it, which is what lets a
+ * global be cleared or redefined. Jest gives each test file its own module registry and runs
+ * `setupFiles` inside it, so what is set here cannot reach another file.
+ *
+ * An argument that is not an options object is refused where it is called, before any step
+ * definition file has loaded. An unknown key is accepted and ignored, exactly as it is per call.
+ */
+export function setFusionConfiguration(options: FusionOptions): void;