npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@simplystated/xstate-to-gherkin

v0.3.0

Published

Generate gherkin test scripts from an xstate statechart

Downloads

4

Readme

xstate-to-gherkin · GitHub license npm version CI

xstate-to-gherkin is a library and cli tool to generate Gherkin test scripts from an XState statechart.

Logo

Quickstart

Check out a codesandbox demo here to play with xstate-to-gherkin from your browser.

You'll need to have an XState machine definition. xstate-to-gherkin requires you to annotate your machine with a few additional pieces of metadata. On any state you would like to make an assertion for, set meta.gherkinAssert to a string describing what should be true in that state. Optionally, on any state that is part of a feature, set meta.gherkinFeature to a string describing that feature. Optionally, on any state that is part of a scenario, set meta.gherkinScenario to a string describing that scenario.

Here's an example.

Assume you have a machine.ts file like this:

const basicWithConditions = createMachine({
  predictableActionArguments: true,
  id: "basicWithConditions",
  initial: "start",
  states: {
    start: {
      meta: {
        // whenever you're in this state, this should be true
        gherkinAssert: "I can see the start page",
        // this state is part of My Feature.
        gherkinFeature: "My Feature",
      },
      on: {
        "I tap the next button": [
          {
            target: "success",
            // guards will be turned into "When ... with <guard>."
            // So this will be turned into "When I tap on the next button with good input"
            cond: "good input",
          },
          {
            target: "failure",
            cond: "bad input",
          },
        ],
      },
    },
    success: {
      meta: {
        gherkinAssert: "I can see the success page",
        gherkinScenario: "Success",
      },
      initial: "successStep1",
      states: {
        successStep1: {
          meta: {
            gherkinAssert: "I see the first step of the success page",
          },
        },
      },
    },
    failure: {
      meta: {
        gherkinAssert: "I see the failure page",
        gherkinScenario: "Failure",
      },
    },
  },
});

After running

npx @simplystated/xstate-to-gherkin --output-dir out machine.ts

You should see a new file, out/my-feature.feature with contents like this:

Feature: My Feature

  Scenario: Success
    Given I can see the start page
    When I tap the next button with good input
    Then I can see the success page
    And I see the first step of the success page

  Scenario: Failure
    Given I can see the start page
    When I tap the next button with bad input
    Then I see the failure page

Using xstate-to-gherkin as a library

Install:

npm install --save-dev @simplystated/xstate-to-gherkin

Then, in code:

import { xstateToGherkinScripts } from "@simplystated/xstate-to-gherkin";
import { createMachine } from "xstate";

const machine = createMachine(...);

// scriptsByFilenames will contain a Map from filenames (e.g. my-feature.feature) to the Gherkin content of the file.
const scriptsByFilenames = xstateToGherkinScripts(machine);

Why would you want to generate a Gherkin script from a statechart?

First off, it's important to note that you can describe any reactive system as a statechart. That means that you can certainly model anything you are trying to test with Gherkin as a statechart. Generally, modeling these types of systems as statecharts is quite straightforward because the structure of the statechart closely matches the way we humans tend to think about these systems.

Next, realize that you need to write a number of test scripts proportional to the number of paths through your system (statechart) if you want to cover all of your functionality. Users do not just experience states; they experience paths through states. Suffice it to say that there are many more paths than there are states. If you try to explicitly list every path, you will have an enormous amount of work to do, especially if you add new edges near your initial state.

So, we can take advantage of the power of the declarative nature of statecharts AND the fact that they are easy to use to model any system we might care about AND the fact that they allow us to do work in proportion to the number of states instead of the number of paths to let our computer do the hard work for us.

Simply Stated

xstate-to-gherkin is a small tool built by Simply Stated. At Simply Stated, our goal is to build all of the tooling you need to experience the full power of statecharts.

License

xstate-to-gherkin is MIT licensed.