It’s frequently touted that Cucumber is “human readable” which at first glance seems to be the case. Examples show clean, easy to read language, that then gets a dozen or so lines of scripting to turn into a real test. Some guides will give warnings about some common code smells from poorly written tests, but that would be as far into reality as the typical guide would give. Cucumber looks like the perfect answer! Why shouldn’t I use cucumber?
In practice, Cucumber scenarios tend to fail in one of two directions: they get broken into so many small steps that non-technical readers stop engaging, or they stay so rigidly worded that implementation winds up with a lot of repeated scripting.
Scene 1
The team has decided (or been told) to create an automated integration test suite. They like a particular cucumber library and decide to start implementing some scenarios. The first few scenarios have potentially big steps, but they read like the examples. Then they start to find scenarios that require slightly different actions. “Log in to X account” becomes “Enter username for X account” “Enter password for X account” and “Submit login information” because they have tests for inputing invalid passwords or invalid usernames.
This stripping down into smaller steps happens more and more over time, and the Cucumber starts to read like the worlds most boring instruction manual. Eventually any non-technical people associated with the project stop reading any of the scenarios and just rubber stamp whatever approval is put in front of them.
Scene 2
The team has decided to automate some of the requirements from the client. Cucumber feels like a natural fit, and so they mutate the requirements list into appropriate cucumber scenarios and then begin implementation. They have already decided to communicate the requirements via Cucumber scenarios with non-technical personnel. And as such they have a very strong requirement not to adjust the steps of the scenarios (other than to line up a step with the exact wording used previously).
The scripting supporting the scenarios quickly balloons in size with copy and pasted code all over the place. Any change in the code suddenly has 4-5 times the baggage as each step that interacts with that change has to be hunted down individually. Eventually automating the integration tests starts to lose its priority and the integration suite is forgotten or abandoned.
The problems
Each of these scenes has issues. Both end with a group alienated from the intent of the integration test and its value diminished or lost. Ultimately, a single jump from technical to non-technical doesn’t really work.
The fixes
Don’t make non-technical stakeholders read it
You can have your cucumber steps be there as a slightly more readable description of technical material. And you can use an entirely different system for communicating expectations with the client. You can still frame things as scenarios, but there are a lot of different ways to describe a scenario, it doesn’t have to be cucumber.
Method calls everywhere
Behind the cucumber step definition, you can do the layer of decomposition via a series of method calls. If you have need to break up “log in” into “input username” “input password” and “submit” you can have the 3 smaller components be methods, and have the 4 different step definitions, reusing the small step methods to build up the more abstract step.
Hybrid
As with most things in this industry, the right answer is “it depends” and sometimes you will need to blend together each of the approaches, or ones that I haven’t thought of, in order to find the right balance for your project. Be careful with having too many layers of abstraction however, as that itself becomes a beast to manage in its own right.
Each of the scenes above are things that happen during most any project where technical and non-technical people have to agree on a definition of the requirements. Realistically most projects that are aware that there is a meaningful fix are going to see themselves get pulled in each direction at different points in time. And I wish the end results I described in each scene were rare enough to be called hyperbole. If you have any stories (success or otherwise) of Cucumber in your projects, drop them in the comments, I would love to hear more about them.
✨ AI Post Recap
Cucumber scenarios marketed as human readable usually fail in one of two ways. They get broken into so many granular steps that non-technical readers stop engaging, or they stay locked to exact wording so tightly that any code change breaks dozens of scripted steps. The fix in both cases is adding an intermediate layer, or accepting more than one jump, between plain language and the code that runs it.
Why do Cucumber tests stop being human readable over time? As scenarios get broken into smaller, more specific steps to handle edge cases, they read more like a technical instruction manual than a description of behavior, and non-technical stakeholders stop engaging with them.
What goes wrong when Cucumber scenarios are locked to exact wording? Any change to the underlying code requires hunting down every scenario step that uses that exact phrasing, since the scripting behind each step is copied and specific rather than reusable.
How do you fix Cucumber tests that have become too technical or too rigid? Add an intermediate layer that decomposes larger steps into reusable method calls, or stop using Cucumber for the parts of the requirements that don’t need non-technical readability.
