Revist the waterfall process but this time with maths
Tags: testing, javascript, statemachine, maths
Published: 2019-08-20 21:31:43

(Cover image by [John Westrock](https://unsplash.com/@johnwestrock?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText) on [Unsplash](https://unsplash.com/search/photos/waterfall?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText))

"Design, maths & framework".

The "you really should read" [Pure UI](https://rauchg.com/2015/pure-ui) and [Pure UI Control](https://medium.com/@asolove/pure-ui-control-ac8d1be97a8d) articles defined an approach to app development (design and creation) which resolves to these 3 words. If their approach to maths is extended slightly to include testing, then we can say these 3 words constitute a comprehensive but simple waterfall development process.

![3-word dev process flow](https://thepracticaldev.s3.amazonaws.com/i/num9dfr6rq80d3bafnp1.png)

I find this an attractive simplification, in which maths helps developer's lives become easier, less stressful and less process-dependent.

*Design* defines the appearance and the core states and transitions. *Maths* formalises the states and transitions, whilst visually and collaboratively supporting the investigation of missing details and then auto-generating tests. The app *framework* simply instantiates those states and transitions.

## Pure UI design

The essence of 'Pure UI', as eloquently described in the articles at the beginning of this post, is a smooth interaction between design and business logic. UI is really a side-effect of the business logic, or state management. The chosen solution to provide this apparent magic is state charts. It doesn't really matter which framework you use, so long as it's functional and state -> UI is uni-directional!

## What are state charts and how do they help?

State charts are a well-described mathematical concept (an [intro](https://statecharts.github.io/) and some [resources](https://statecharts.github.io/resources.html)) which extend the simpler state machine. The core principles are the definition of states, transitions between states and actions to take in consequence. Optional extras are the management of state and implementation of the actions (I prefer to let the app or UI framework deal with these).

A state chart allows reasoning about function without concern for implementation details - it is therefore easier. In particular, [visualisation](https://xstate.js.org/viz/?gist=61fb76fa71bd9216a21c70d1f241da91) of a state chart enables easy collaboration with designers and rapid prototyping (or updating) of function. The linked visualisation is from the app example in 'Implementation options' below, and is a simple copy-paste of a state chart from the [machines.js](https://github.com/johnkazer/hyperapp-xstate-demo/blob/xstate/src/machines.js) file in that app. A state chart designed in this way can therefore be used directly in code.

## Automated testing with state charts

Much, of course, is written about unit tests. Functional programming, a natural fit for state machines and React or Hyperapp means unit tests are reasonably straightforward. What is always less so is testing business logic, or the interactions between functions and state which happen when the UI generates related sequences of events.

Cypress can automate business logic testing if state chart 'paths' are provided, which represent automatically generated routes or sequences of transitions. XState has a [graph module](https://xstate.js.org/docs/packages/xstate-graph/#quick-start) which does this.

There are less than 10 simple app-specific lines of code, amongst re-usable functions, which drive the [Cypress test](https://github.com/johnkazer/hyperapp-xstate-demo/blob/xstate/cypress/integration/tests.js) of each app state and valid 'path'. You can watch the test video 'live' [here](https://github.com/johnkazer/hyperapp-xstate-demo/blob/xstate/cypress/videos/tests.js.mp4) and the app is [hosted here](https://picswithhyperappxstate.z33.web.core.windows.net/) (it is a simple media creation [PWA](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps), which doesn't send data anywhere but asks for video, audio and push notification permissions).

## Maintenance

New requirements simply filter in from the top, via design updates and logical consequences of state chart changes. In principle the tests will automatically update as a function of the state charts (in practice some small amount of manual input may be required).

## Implementation options

There are some details to work out regarding the specific boundary of responsibility between the maths and the app framework (e.g. exactly who hosts the state) but these don't change the principles.

For instance, in [this example](https://dev.to/johnkazer/use-maths-not-process-for-reliable-web-apps-1bmm), the [Hyperapp](https://hyperapp.dev/) framework is responsible for managing state and executing actions. However in [this](https://codesandbox.io/s/xstate-todomvc-33wr94qv1?from-embed) example [React](https://reactjs.org/) is largely just an interface to the browser's DOM whilst the state chart (from [XState](https://xstate.js.org)) manages state and action execution. Specifically in this case, DOM events are linked to a [React Hook](https://xstate.js.org/docs/packages/xstate-react/#api) which triggers a state transition - the state chart does the rest.

A very useful (but little written about?) state chart feature is that they can automatically provide app use-cases as sequences of state transitions. These sequences, or paths, can be used as the basis for testing - [this example](https://dev.to/johnkazer/use-maths-not-process-for-reliable-web-apps-1bmm) drives [Cypress](https://www.cypress.io/) in this way. The repository is [here](https://github.com/johnkazer/hyperapp-xstate-demo) - use the 'xstate' branch.

## Waterfalls with maths

So there you have it - a waterfall dev process that is much simpler and friendlier than I remember. And some maths that isn't scary and is useful!

An example development process flow might look something like this:

1. Creating the initial *design* with [Figma](https://www.figma.com/) and [sketch.systems](https://sketch.systems/ryanlucas/sketch/a58505b25ac114c6cec64922cb8fb325) (use [this Figma plugin](https://github.com/johnkazer/Export-Figma-layer-IDs) and see the 'Export to clipboard' option in sketch.systems) which informs, and is informed by;

1. State chart *maths* in [XState](https://xstate.js.org/).

1. UI via a *framework* (such as [React](https://reactjs.org/) or [Hyperapp](https://hyperapp.dev/)) is a side-effect of state chart behaviour.

1. Testing can be derived directly from the state chart *maths* and implemented with [Cypress](https://www.cypress.io/).

1. Requirement changes can quickly be incorporated into *design* and state chart *maths* updates, which (generally) require simple UI *framework* tweaks.