racejar 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2016 - 2024 Sanity.io
+
+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,254 @@
+# `racejar`
+
+> A testing framework agnostic [Gherkin](https://cucumber.io/docs/gherkin/reference/) driver
+
+`racejar` is a thin wrapper around `@cucumber/*` that allows you to write your tests in Gherkin and run them with [Vitest](https://vitest.dev/), [Jest](https://jestjs.io/) or any other testing framework of your choice.
+
+```sh
+pnpm add --save-dev racejar
+```
+
+## Usage with Vitest
+
+Using `racejar` with Vitest requires no additional configuration. Just drop it into a new or an existing test file and get going:
+
+```ts
+// your.test.ts
+
+// Import `Feature` from `racejar/vitest`
+import {Feature} from 'racejar/vitest'
+// Import your raw `.feature` file
+import featureFile from './your.feature?raw'
+
+// Run the feature
+Feature({
+  featureText: featureFile,
+  stepDefinitions: [
+    // ...
+  ],
+  parameterTypes: [
+    // ...
+  ],
+})
+```
+
+## Usage with Jest
+
+Using `racejar` with Jest is similar to Vitest. Just import `Feature` from `racejar/jest` instead.
+
+However, Jest can't import raw files out of the box. You'll need a transformer. Luckily, it's easy to write and configure a simple one:
+
+```ts
+// jest.config.ts
+
+import type {Config} from 'jest'
+
+const config: Config = {
+  transform: {
+    '\\.feature$': '<rootDir>/feature-file-transformer.js',
+  },
+}
+```
+
+```js
+// feature-file-transformer.js
+
+module.exports = {
+  process(content) {
+    return {
+      code: `module.exports = ${JSON.stringify(content)};`,
+    }
+  },
+}
+```
+
+## Usage with \<your favourite testing framework\>
+
+`Feature` exported from `racejar/vitest` and `racejar/jest` are convenient thin wrappers around the more generic `compileFeature`.
+
+If you are unhappy with those wrappers or want to use `racejar` with another framework, then you can compile your feature manually and run your tests using the compiled feature:
+
+```ts
+import {compileFeature} from 'racejar'
+
+const feature = compileFeature({
+  featureText: featureFile,
+  stepDefinitions: [
+    // ...
+  ],
+  parameterTypes: [
+    // ...
+  ],
+})
+
+for (const scenario of feature.scenarios) {
+  // ...
+}
+```
+
+## Define Steps and Parameter Types
+
+`stepDefinitions` can be defined inline or separately. They are defined using `Given`, `When`, `Then` exported from `racejar`:
+
+```ts
+import {Given, Then, When} from 'racejar'
+
+const stepDefinitions = [Given(/* ... */), When(/* ... */), Then(/* ... */)]
+```
+
+`racejar` will error out and inform you if a step definition is missing or if you accidentally defined duplicate definitions.
+
+If you use nonstandard parameter types, then you can define them yourself:
+
+```ts
+import {createParameterType} from 'racejar'
+
+const parameterTypes = [createParameterType(/* ... */)]
+```
+
+## Example Usage
+
+The following example is taken from the [`editor`](/packages/editor/) package in this repository. For a full example of how to use `racejar`, head over to [/packages/editor/gherkin-tests/](/packages/editor/gherkin-tests/). The package uses `racejar` to run a [Playwright](https://playwright.dev/) E2E test suite powered by [Vitest Browser Mode](https://vitest.dev/guide/browser/).
+
+This feature file tests that the editor can annotate text and additionally asserts the text selection after an annotation is applied. It uses 7 steps which need to be defined:
+
+```gherkin
+// annotations.feature
+
+Feature: Annotations
+
+  Background:
+    Given one editor
+    And a global keymap
+
+  Scenario: Selection after adding an annotation
+    Given the text "foo bar baz"
+    When "bar" is selected
+    And "link" "l1" is toggled
+    Then "bar" has marks "l1"
+    And "bar" is selected
+```
+
+Here's a rough idea of how these steps can be defined:
+
+```tsx
+import {Given, Then, When} from 'racejar'
+
+// A `context` object is passed around between steps
+// The context can be whatever you want it to be
+type Context = {
+  locator: Locator
+  keyMap: Map<string, string>
+}
+
+export const stepDefinitions = [
+  Given('one editor', async (context: Context) => {
+    render(<Editor />)
+    const locator = page.getByTestId('<editor test ID>')
+    context.locator = locator
+    await vi.waitFor(() => expect.element(locator).toBeInTheDocument())
+  }),
+  Given('a global keymap', (context: Context) => {
+    context.keyMap = new Map()
+  }),
+  Given('the text {string}', async (context: Context, text: string) => {
+    await userEvent.click(context.locator)
+    await userEvent.type(context.locator, text)
+  }),
+  Given('{string} is selected', async (context: Context, text: string) => {
+    // Select `text` in the editor
+  }),
+  When(
+    '{annotation} {keys} is toggled',
+    async (
+      context: Context,
+      annotation: 'comment' | 'link',
+      keyKeys: Array<string>,
+    ) => {
+      // Toggle the `annotation` and store the resulting keys on the `context.keyMap`
+    },
+  ),
+  Then(
+    '{string} has marks {marks}',
+    async (context: Context, text: string, marks: Array<string>) => {
+      // Get the actual marks on the `text` and compare them with `marks`
+    },
+  ),
+  Then('{text} is selected', async (context: Context, text: Array<string>) => {
+    // Assert that the current editor selection matches `text`
+  }),
+]
+```
+
+As you can see, the step definitions declare a few custom parameters, `{annotation}`, `{keys}` and `{text}`:
+
+```ts
+import {createParameterType} from 'racejar'
+
+export const parameterTypes = [
+  createParameterType({
+    name: 'annotation',
+    matcher: /"(comment|link)"/,
+  }),
+  createParameterType({
+    name: 'keys',
+    matcher: /"(([a-z]\d)(,([a-z]\d))*)"/,
+    type: Array,
+    transform: (input) => input.split(','),
+  }),
+  createParameterType({
+    name: 'text',
+    matcher: /"([a-z-,#>\\n |\[\]]*)"/,
+    type: Array,
+    transform: parseGherkinTextParameter,
+  }),
+]
+
+function parseGherkinTextParameter(text: string) {
+  return text
+    .replace(/\|/g, ',|,')
+    .split(',')
+    .map((span) => span.replace(/\\n/g, '\n'))
+}
+```
+
+Now, let's run the test using our defined steps and custom parameter types:
+
+```ts
+// annotations.test.ts
+
+import annotationsFeature from './annotations.feature?raw'
+import {parameterTypes} from './parameter-types'
+import {stepDefinitions} from './step-definitions'
+
+Feature({
+  featureText: annotationsFeature,
+  stepDefinitions,
+  parameterTypes,
+})
+```
+
+## Tips
+
+If TypeScript errors out with `Cannot find module '.your.feature?raw' or its corresponding type declarations.` then you can declare `.*feature?raw` files as modules:
+
+```ts
+// global.d.ts
+
+declare module '*.feature?raw' {
+  const content: string
+  export default content
+}
+```
+
+---
+
+Use [prettier-plugin-gherkin](https://github.com/mapado/prettier-plugin-gherkin) to automatically format your `.feature` files.
+
+```json
+// .prettierrc
+
+{
+  "plugins": ["prettier-plugin-gherkin"]
+}
+```

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "racejar",
+  "version": "0.0.1",
+  "description": "A testing framework agnostic Gherkin driver",
+  "keywords": [
+    "cucumber",
+    "gherkin",
+    "jest",
+    "test",
+    "vitest"
+  ],
+  "homepage": "https://www.sanity.io/",
+  "bugs": {
+    "url": "https://github.com/portabletext/editor/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/portabletext/editor.git",
+    "directory": "packages/racejar"
+  },
+  "license": "MIT",
+  "author": "Sanity.io <hello@sanity.io>",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "default": "./src/index.ts",
+      "types": "./src/index.ts"
+    },
+    "./jest": {
+      "default": "./src/jest/index.ts",
+      "types": "./src/jest/index.ts"
+    },
+    "./vitest": {
+      "default": "./src/vitest/index.ts",
+      "types": "./src/vitest/index.ts"
+    }
+  },
+  "devDependencies": {
+    "@cucumber/cucumber-expressions": "^18.0.1",
+    "@cucumber/gherkin": "^30.0.4",
+    "@cucumber/messages": "^27.0.2",
+    "@jest/globals": "^29.7.0",
+    "@sanity/pkg-utils": "^6.11.12",
+    "typescript": "5.6.3",
+    "vitest": "^2.1.5"
+  },
+  "peerDependencies": {
+    "@jest/globals": "^29.7.0",
+    "vitest": "^2.1.1"
+  },
+  "scripts": {
+    "check:lint": "biome lint .",
+    "check:types": "tsc",
+    "lint:fix": "biome lint --write ."
+  }
+}

package/src/compile-feature.ts

@@ -0,0 +1,142 @@
+import type {ParameterType} from '@cucumber/cucumber-expressions'
+import {
+  CucumberExpression,
+  ParameterTypeRegistry,
+} from '@cucumber/cucumber-expressions'
+import * as Gherkin from '@cucumber/gherkin'
+import * as Messages from '@cucumber/messages'
+import type {
+  StepDefinition,
+  StepDefinitionCallbackParameters,
+} from './step-definitions'
+
+/**
+ * @public
+ */
+export type CompiledFeature = {
+  name: string
+  tag?: 'only' | 'skip'
+  scenarios: Array<{
+    name: string
+    tag?: 'only' | 'skip'
+    steps: Array<() => Promise<void>>
+  }>
+}
+
+/**
+ * @public
+ */
+export function compileFeature<TContext extends Record<string, any> = object>({
+  featureText,
+  stepDefinitions,
+  parameterTypes,
+}: {
+  featureText: string
+  stepDefinitions: Array<StepDefinition<TContext, any, any, any>>
+  parameterTypes: Array<ParameterType<unknown>>
+}): CompiledFeature {
+  const uuidFn = Messages.IdGenerator.uuid()
+  const builder = new Gherkin.AstBuilder(uuidFn)
+  const matcher = new Gherkin.GherkinClassicTokenMatcher()
+  const parser = new Gherkin.Parser(builder, matcher)
+
+  const gherkinDocument = parser.parse(featureText)
+  const pickles = Gherkin.compile(
+    gherkinDocument,
+    (gherkinDocument.feature?.name ?? '').replace(' ', '-'),
+    uuidFn,
+  )
+
+  const parameterTypeRegistry = new ParameterTypeRegistry()
+  parameterTypes.forEach((parameterType) =>
+    parameterTypeRegistry.defineParameterType(parameterType),
+  )
+
+  if (!gherkinDocument.feature) {
+    throw new Error('No feature found')
+  }
+
+  const stepImplementations = stepDefinitions.map((stepDefinition) => {
+    const expression = new CucumberExpression(
+      stepDefinition.text,
+      parameterTypeRegistry,
+    )
+
+    return {
+      type: stepDefinition.type,
+      text: stepDefinition.text,
+      expression,
+      callback: stepDefinition.callback,
+    }
+  })
+
+  const skippedFeature = gherkinDocument.feature.tags.some(
+    (tag) => tag.name === '@skip',
+  )
+  const onlyFeature = gherkinDocument.feature.tags.some(
+    (tag) => tag.name === '@only',
+  )
+
+  if (skippedFeature && onlyFeature) {
+    throw new Error('Feature cannot have both @skip and @only tags')
+  }
+
+  const scenarios = pickles.map((pickle) => {
+    const skippedPickle = pickle.tags.some((tag) => tag.name === '@skip')
+    const onlyPickle = pickle.tags.some((tag) => tag.name === '@only')
+    const context = {} as TContext
+
+    const steps = pickle.steps.map((step) => {
+      const matchingSteps = stepImplementations
+        .filter((stepImplementation) => stepImplementation.type === step.type)
+        .flatMap((stepImplementation) => {
+          const args = stepImplementation.expression.match(step.text)
+
+          if (args) {
+            return [
+              {
+                ...stepImplementation,
+                args,
+              },
+            ]
+          }
+
+          return []
+        })
+
+      const matchingStep = matchingSteps[0]
+
+      if (!matchingStep) {
+        throw new Error(`No implementation found for step: ${step.text}`)
+      }
+
+      if (matchingSteps.length > 1) {
+        throw new Error(`Multiple implementations found for step: ${step.text}`)
+      }
+
+      const args = matchingStep.args.map((arg) =>
+        arg.getValue(matchingStep),
+      ) as StepDefinitionCallbackParameters<any, any, any>
+
+      return () => matchingStep.callback(context, ...args)
+    })
+
+    return {
+      name: pickle.name,
+      tag: skippedFeature
+        ? ('skip' as const)
+        : skippedPickle
+          ? ('skip' as const)
+          : onlyPickle
+            ? ('only' as const)
+            : undefined,
+      steps,
+    }
+  })
+
+  return {
+    tag: skippedFeature ? 'skip' : onlyFeature ? 'only' : undefined,
+    name: gherkinDocument.feature.name,
+    scenarios,
+  }
+}

package/src/create-parameter-type.ts

@@ -0,0 +1,27 @@
+import {ParameterType, type RegExps} from '@cucumber/cucumber-expressions'
+
+/**
+ * @public
+ */
+export type ParameterTypeConfig<TType = string> = {
+  readonly name: string
+  matcher: RegExps
+  type?: (...args: unknown[]) => TType
+  transform?: (...match: string[]) => TType
+}
+
+/**
+ * @public
+ */
+export function createParameterType<TType = string>(
+  config: ParameterTypeConfig<TType>,
+): ParameterType<TType> {
+  return new ParameterType(
+    config.name,
+    config.matcher,
+    config.type ?? String,
+    config.transform,
+    false,
+    true,
+  )
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './compile-feature'
+export * from './create-parameter-type'
+export * from './step-definitions'

package/src/jest/index.ts

@@ -0,0 +1 @@
+export * from './jest-gherkin-driver'

package/src/jest/jest-gherkin-driver.ts

@@ -0,0 +1,47 @@
+import type {ParameterType} from '@cucumber/cucumber-expressions'
+import {describe, test} from '@jest/globals'
+import {compileFeature} from '../compile-feature'
+import type {StepDefinition} from '../step-definitions'
+
+/**
+ * @public
+ */
+export function Feature<TContext extends Record<string, any> = object>({
+  featureText,
+  stepDefinitions,
+  parameterTypes,
+}: {
+  featureText: string
+  stepDefinitions: Array<StepDefinition<TContext, any, any, any>>
+  parameterTypes: Array<ParameterType<unknown>>
+}) {
+  const feature = compileFeature({
+    featureText,
+    stepDefinitions,
+    parameterTypes,
+  })
+
+  const describeFn =
+    feature.tag === 'only'
+      ? describe.only
+      : feature.tag === 'skip'
+        ? describe.skip
+        : describe
+
+  describeFn(feature.name, () => {
+    for (const scenario of feature.scenarios) {
+      const testFn =
+        scenario.tag === 'only'
+          ? test.only
+          : scenario.tag === 'skip'
+            ? test.skip
+            : test
+
+      testFn(scenario.name, async () => {
+        for (const step of scenario.steps) {
+          await step()
+        }
+      })
+    }
+  })
+}

package/src/step-definitions.ts

@@ -0,0 +1,86 @@
+/**
+ * @public
+ */
+export type StepDefinitionCallbackParameters<
+  TParamA = undefined,
+  TParamB = undefined,
+  TParamC = undefined,
+> = TParamA extends undefined
+  ? []
+  : TParamB extends undefined
+    ? [TParamA]
+    : TParamC extends undefined
+      ? [TParamA, TParamB]
+      : [TParamA, TParamB, TParamC]
+
+/**
+ * @public
+ */
+export type StepDefinitionCallback<
+  TContext extends Record<string, any> = object,
+  TParamA = undefined,
+  TParamB = undefined,
+  TParamC = undefined,
+> = (
+  context: TContext,
+  ...args: StepDefinitionCallbackParameters<TParamA, TParamB, TParamC>
+) => Promise<void>
+
+/**
+ * @public
+ */
+export type StepDefinition<
+  TContext extends Record<string, any> = object,
+  TParamA = undefined,
+  TParamB = undefined,
+  TParamC = undefined,
+> = {
+  type: 'Context' | 'Action' | 'Outcome'
+  text: string
+  callback: StepDefinitionCallback<TContext, TParamA, TParamB, TParamC>
+}
+
+/**
+ * @public
+ */
+export function Given<
+  TContext extends Record<string, any> = object,
+  TParamA = undefined,
+  TParamB = undefined,
+  TParamC = undefined,
+>(
+  text: string,
+  callback: StepDefinitionCallback<TContext, TParamA, TParamB, TParamC>,
+): StepDefinition<TContext, TParamA, TParamB, TParamC> {
+  return {type: 'Context', text, callback}
+}
+
+/**
+ * @public
+ */
+export function When<
+  TContext extends Record<string, any> = object,
+  TParamA = undefined,
+  TParamB = undefined,
+  TParamC = undefined,
+>(
+  text: string,
+  callback: StepDefinitionCallback<TContext, TParamA, TParamB, TParamC>,
+): StepDefinition<TContext, TParamA, TParamB, TParamC> {
+  return {type: 'Action', text, callback}
+}
+
+/**
+ * @public
+ */
+export function Then<
+  TContext extends Record<string, any> = object,
+  TParamA = undefined,
+  TParamB = undefined,
+  TParamC = undefined,
+>(
+  text: string,
+  callback: StepDefinitionCallback<TContext, TParamA, TParamB, TParamC>,
+): StepDefinition<TContext, TParamA, TParamB, TParamC> {
+  return {type: 'Outcome', text, callback}
+}

package/src/vitest/index.ts

@@ -0,0 +1 @@
+export * from './vitest-gherkin-driver'

package/src/vitest/vitest-gherkin-driver.ts

@@ -0,0 +1,47 @@
+import type {ParameterType} from '@cucumber/cucumber-expressions'
+import {describe, test} from 'vitest'
+import {compileFeature} from '../compile-feature'
+import type {StepDefinition} from '../step-definitions'
+
+/**
+ * @public
+ */
+export function Feature<TContext extends Record<string, any> = object>({
+  featureText,
+  stepDefinitions,
+  parameterTypes,
+}: {
+  featureText: string
+  stepDefinitions: Array<StepDefinition<TContext, any, any, any>>
+  parameterTypes: Array<ParameterType<unknown>>
+}) {
+  const feature = compileFeature({
+    featureText,
+    stepDefinitions,
+    parameterTypes,
+  })
+
+  const describeFn =
+    feature.tag === 'only'
+      ? describe.only
+      : feature.tag === 'skip'
+        ? describe.skip
+        : describe
+
+  describeFn(feature.name, () => {
+    for (const scenario of feature.scenarios) {
+      const testFn =
+        scenario.tag === 'only'
+          ? test.only
+          : scenario.tag === 'skip'
+            ? test.skip
+            : test
+
+      testFn(scenario.name, async () => {
+        for (const step of scenario.steps) {
+          await step()
+        }
+      })
+    }
+  })
+}

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "@sanity/pkg-utils/tsconfig/strictest.json",
+  "compilerOptions": {
+    "noEmit": true
+  },
+  "include": ["src"]
+}