[This article was first published on jakub::sobolewski, and kindly contributed to R-bloggers]. (You can report issue about the content on this page here)Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.When writing specifications, it’s easy to get caught up in implementation details, especially when adding specifications after the software was built.Let’s see how we can add specifications for existing code and get Cucumber specifications that reflect business concepts rather than UI specifics that makes extension and maintenance easier.The SetupLet’s imagine an app with a workflow as follows:The app opens on a “Data” page, with a stepper for: Upload → Filtering → Mapping → Preview.Users upload or select a default dataset, then proceed step by step.After submitting variable mappings, a data preview appears.Once this is complete, a “Visualization” feature becomes available for viewing plots.This workflow is quite straightforward, but also quite complex.Writing robust, executable specifications for it demands that we express its logic without exposing underlying UI details.1. Define Behavior, Not ImplementationShift away from UI or implementation-specific language. For example:Avoid: Given the user starts on the Data pagePrefer: Given the user begins a new data preparation sessionThis abstraction ensures scenarios remain stable regardless of changes to the UI or technology stack. The scenario should apply equally well whether the system is a web app, command-line interface, or something else entirely.2. Capture the Flow in GherkinBreak the user flow down into core business steps:Start a new data preparation sessionProvide a dataset (custom or default)Optionally apply filtersSubmit variable mappingsView a data previewGain access to visualizationView a plotDraft scenarios using the Given–When–Then cadence to focus on outcomes and user intentions rather than specific technical steps. This cadence is fundamental BDD best practice, improving clarity and maintainability.ExampleFeature: Data visualization This feature describes the core user flow for preparing a dataset and accessing visualizations. The workflow includes optional and required steps before plots can be viewed. Background: Given the user begins a new data preparation session Scenario: User completes the workflow using a custom dataset Given the user provides a dataset When the user proceeds to the Filtering step And the user skips filtering And the user proceeds to the Mapping step And the user accepts the default variable mapping When the user submits the mapping Then the user reaches the Preview step And the dataset is available for inspection And the Visualization feature becomes available Scenario: User completes the workflow using a default dataset Given the user chooses to use a default dataset When the user proceeds through the Filtering step without applying filters And the user accepts the default variable mapping And the user submits the mapping Then the user reaches the Preview step And the dataset is available for inspection And the Visualization feature becomes available Scenario: Visualization is not available before data preparation Given the Visualization feature is not accessible When the user provides a dataset And the user skips filtering And the user accepts the default variable mapping And the user submits the mapping Then the Visualization feature becomes accessible Scenario: User views a plot after completing data preparation Given the user has completed the data preparation workflow When the user accesses the Visualization section And the user chooses to inspect Individual Plots Then the user sees a visualization of the dataset3. Review Your SpecificationsAvoid technical or UI phrasing: Write steps as business actions, not clicks or UI navigation. For instance, use “submit the mapping” instead of “click Submit.”Use correct scenario structure: Always adhere to the Given–When–Then cadence for clarity and consistency. Don’t mix up the order. To keep the scenarios readable, you can use alternative steps phrasings like “And” or “But”.Favor reusable, high-level steps: Steps like the user provides a dataset or the user submits the mapping are platform-agnostic and extensible. This makes feature files easier to read, update, and automate.Iterate with AIUse this prompt to make AI assist you in writing Gherkin scenarios:I'm adding Cucumber tests to an app. You're a BDD expert helping me discover business concepts and user flows.I will provide a description of how I interact with the app. Your task is to help me write executable specifications for given description. When writing specifications:- Don't reveal implementation details (like UI elements).- Imagine at least 3 different ways this system could be implemented, e.g. CLI, API, mind control. Those specifications need to be true no matter how the system is implemented.- Always use the Given–When–Then cadence.If something is not clear, ask me questions.Starting with this prompt, you can follow the process:Provide description of what you can do with the app.AI will suggest Gherkin steps.Review the steps, and ask AI to build scenarios.Review the scenarios, and iterate as needed.This can help you refine your specifications and ensure they accurately capture the desired user behavior.When working with AI, pay attention to not accidentally reveal confidential information. Write your app description carefully.Abstracting away from implementation details, especially if they already exist, is difficult.But it is crucial for writing maintainable and extensible specifications. By focusing on user behavior and outcomes, you can create specifications that remain relevant even as the underlying technology evolves.And with the help of AI, you get a fresh perspective on your application, which can lead to creating better specifications.To leave a comment for the author, please follow the link and comment on their blog: jakub::sobolewski.R-bloggers.com offers daily e-mail updates about R news and tutorials about learning R and many other topics. Click here if you're looking to post or find an R/data-science job.Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.Continue reading: How to Write Cucumber Specifications the Right Way: From App Description to Scenarios