Moving production code example out from test code

[Frenetikon]

🤔 What's changed?

isItFriday business logic was presented in test code. AStepDefinition file should not contain business logic, but call it. In the 10-minutes-tutorial I moved the logic out to a separated code file, (under a production related package com.domain.prod.example, where applicable) to emphasise its different nature.

⚡️ What's your motivation?

There is no open issue for this yet.
My motivation was that it was misleading. Keeping business example in the Step Definition file disrupted the trilogy of Scenario Definition - Step Definition - Production codes. Following such tutorial can lead to an inelegant solution.

🏷️ What kind of change is this?

• 📖 Documentation (improvements without changing code)

♻️ Anything particular you want feedback on?

I did not have Docusaurus server to run the mdx files.

📋 Checklist:

• I agree to respect and uphold the Cucumber Community Code of Conduct

---

This text was originally generated from a template, then edited by hand. You can modify the template here.

[netlify]

✅ Deploy Preview for cucumber-website-preview ready!

Name	Link
🔨 Latest commit	f58e74e
🔍 Latest deploy log	https://app.netlify.com/projects/cucumber-website-preview/deploys/6930498c951cc10008c6bca0
😎 Deploy Preview	https://deploy-preview-178--cucumber-website-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[mpkorstanje]

Heya! That's an intentional part of the tutorial. The tutorial follows the red-green-refactor pattern. Actually extracting the code out is mentioned at the end and left as an exercise for the reader.

https://cucumber.io/docs/guides/10-minute-tutorial/?lang=java#refactoring

[Frenetikon]

My concern is more about what kind of design we’re modelling while we’re teaching”:
1. It teaches mixing layers.
Putting IsItFriday class directly in the step definition means the step file temporarily contains both test glue and production behaviour. In real life, it would never be done like that. For many beginners this is their first exposure to Cucumber, and they’re likely to copy-paste that structure into real projects without ever doing the final extraction exercise.
2. It clashes with the message of BDD.
The docs (and other Cucumber material) normally stress the separation between
scenario → step definition → production code. But here the tutorial does not follow this, only it fixes the whole in the end. Step definitions are glue, they shouldn’t contain business logic ever. The tutorial is effectively modelling the opposite.
3. Separation does not break the red–green–refactor flow.
We can still demonstrate the TDD cycle while keeping production code in a small IsItFriday class from the start.

Putting production logic into step definitions as the starting point, for newcomers looks like an endorsed pattern, instead of a deliberate code smell.

[mpkorstanje]

Doing the absolute minimum is a common TDD pattern. The intermediate "mess" is a feature of the process, not a bug.

Also keep in mind that the purpose of the 10 minute tutorial is to get people started quickly. Not teach them about separation of concerns or refactoring just yet.

From a practical perspective the tutorial also has to teach this (at present) in 4 different languages. So not fleshing out the refactor step makes it easier to maintain and keeps the tutorial short.

So yes, it is not a perfect demonstration of BDD or TDD and it doesn't follow best practices. But that also wasn't the aim here.

That said. I don't see any harm in fleshing out the refactor step and cleaning up the mess. Though this would have to be done in 4 languages. I realize it is a much bigger ask than what you've offered so far but would this be something you're willing to contribute?

[Frenetikon]

Im my PR, I already managed the 4 language variations. I did not notice the refactoring section in the end, what makes no sense after my changes, so with that change I have to update my PR.

I think even a 10-minute tutorial should not promote intermediate mess.

[mpkorstanje]

I think even a 10-minute tutorial should not promote intermediate mess.

As an end state no. But as an intermediate step it is essential for teaching and learning.

• It keeps the amount of things that need to be done get to a working state minimal.
• It shows people new to writing software what we consider a mess.
• It provides an opportunity to teach how to clean up the mess by refactoring and use the tests to ensure nothing broke.

If you think otherwise I'm happy to disagree on that and we can close the PR. But if you want to expand on the refactoring section that cleans up the mess, I would gladly accept that as a PR.

[Frenetikon]

Thanks for your clarifications and explanations.

I do understand the red–green–refactor practice and thanks for explaining the original intentions of the "intermediate mess". My concern is that, in this specific 10-minute tutorial, the business logic is so trivial that designers fabricated an artificial “mess”, and present an anti-pattern in order to have something to refactor. Meanwhile the main purpose of this page is to demonstrate how Cucumber works in 10 minutes (e.g. how it generates step definitions), not to show a complete TDD/BDD course.
In addition, during a short “getting started” guide, many beginners will stop at the first “ahh, all green” state and copy that structure into real projects (psychological effect of green).
For these reasons, I still believe this example page could be clearer and safer if either:
• we treat it as an edge case and place the codes properly from the start, and page explicitly states that due to the business code simplicity the refactor step is missing, or
• we choose a slightly richer code example that is complex enough to show all three TDD steps and proper code placement, yet still simple enough to fit into 10 minutes without confusing beginners.

With this in mind, I’d kindly ask you to reconsider my proposal.

[mpkorstanje]

I'm afraid we'll have to disagree.