From c8e0bb7d1662f72dc2bca90547c5b0732006f151 Mon Sep 17 00:00:00 2001 From: Leynos Date: Sat, 19 Jul 2025 17:44:47 +0100 Subject: [PATCH] Reference additional sources --- ...havioural-testing-in-rust-with-cucumber.md | 77 +++++++++++++------ 1 file changed, 55 insertions(+), 22 deletions(-) diff --git a/docs/behavioural-testing-in-rust-with-cucumber.md b/docs/behavioural-testing-in-rust-with-cucumber.md index 1e521927..01ab8442 100644 --- a/docs/behavioural-testing-in-rust-with-cucumber.md +++ b/docs/behavioural-testing-in-rust-with-cucumber.md @@ -36,9 +36,10 @@ ambiguity and rework. ### 1.2 The Gherkin Language: Structuring Behaviour To facilitate this process, BDD frameworks like Cucumber use a specific Domain- -Specific Language (DSL) called Gherkin.[^5] Gherkin provides a simple, -structured grammar for writing executable specifications in plain text files -with a `.feature` extension.[^6] Its syntax is designed to be intuitive and +Specific Language (DSL) called Gherkin.[^4][^5] Other tools, such as Robot +Framework, also adopt this style.[^8] Gherkin provides a simple, structured +grammar for writing executable specifications in plain text files with a +`.feature` extension.[^6] Its syntax is designed to be intuitive and accessible, enabling clear communication across different project roles.[^3] A Gherkin document is line-oriented, with most lines beginning with a specific @@ -59,11 +60,11 @@ specifications.[^7] ### 1.3 The Given-When-Then Idiom: A Universal Test Pattern -For developers, the `Given-When-Then` structure is not an entirely new concept. -It is a highly effective reformulation of well-established testing patterns -that many are already familiar with from unit testing.[^5] The most common -parallel is the **Arrange-Act-Assert (AAA)** pattern, conceptualized by Bill -Wake. +For developers, the `Given-When-Then` structure is not an entirely new +concept.[^10] It is a highly effective reformulation of well-established +testing patterns that many are already familiar with from unit testing.[^5] The +most common parallel is the **Arrange-Act-Assert (AAA)** pattern, +conceptualized by Bill Wake. - **Given** corresponds to **Arrange**: This phase sets up the world. It establishes all preconditions, initializes objects, and brings the system @@ -89,7 +90,7 @@ shared, executable documentation. Setting up a Rust project to use the `cucumber` crate requires a few specific configurations in `Cargo.toml` and a well-defined directory structure. This -section walks through creating a minimal, runnable test suite from scratch. +section walks through creating a minimal, runnable test suite from scratch.[^19] ### 2.1 Configuring `Cargo.toml` @@ -107,7 +108,7 @@ console.[^13] | Section | Key | Value / Description | | ------------------ | -------- | ----------------------------------------------------------------------------------------------------- | | [dependencies] | tokio | The async runtime. Required with features like macros and rt-multi-thread.[^13] | -| [dev-dependencies] | cucumber | The main testing framework crate.[^16] | +| [dev-dependencies] | cucumber | The main testing framework crate.[^16][^17] | | [dev-dependencies] | futures | Often needed for async operations, particularly with older examples or for specific combinators.[^18] | | [[test]] | name | The name of the test-runner file (e.g., "cucumber"). This must match the filename in tests/. | | [[test]] | harness | Must be set to `false` so cucumber can manage test execution and output.[^14] | @@ -157,7 +158,7 @@ The `.feature` files in `tests/features/` define *what* the system should do. These can be read, written, and reviewed by non-technical stakeholders. The Rust files in `tests/steps/` define *how* those behaviours are tested. This clear boundary is a cornerstone of effective BDD practice and is strongly -recommended.[^14] +recommended.[^14][^15] ### 2.3 The `World` Object: Managing Scenario State @@ -451,7 +452,7 @@ boilerplate. Sometimes, a step requires a more complex data structure than can be passed with simple arguments. For example, setting up an initial inventory or -providing a list of users. For this, Gherkin provides **Data Tables**.[^23] +providing a list of users. For this, Gherkin provides **Data Tables**.[^23][^24] A Data Table is a pipe-delimited table placed directly after a Gherkin step. To access this table in a Rust step definition, add a @@ -663,12 +664,14 @@ because starting the `MockServer` is an async operation and cannot be done in a `wiremock-rs` is a pure-Rust library for mocking HTTP-based APIs.[^27] Expectations can be defined (for example, "expect a GET request to `/foo`") and specify responses. This is done in the `Given` steps to set up the state of the -external world before the `When` action occurs. +external world before the `When` action occurs. For a deeper look at using +`wiremock` in testing, see Julio Merino's tutorial on unit-testing web services +in Rust.[^28] Using an in-process mock server like `wiremock-rs` is a superior pattern for integration testing. It avoids the complexity and slowness of managing external services or Docker containers, leading to faster and more reliable test -execution.[^27] +execution.[^27] BrowserStack also offers advice on Cucumber best practices.[^29] ### 5.4 Implementing the API Step Definitions @@ -976,8 +979,8 @@ The process involves two main steps: 2. **Publish reports:** Many CI platforms can parse and display test results in a structured format. The `cucumber` crate supports generating JUnit XML reports via the `output-junit` feature flag.[^16] These XML files can then - be published as test artifacts for platforms like GitHub Actions, GitLab CI, - or Jenkins to consume.[^33] + be published as test artifacts for platforms like GitHub Actions, GitLab + CI,[^34] or Jenkins to consume.[^33] This CI integration closes the BDD loop. The `.feature` files, once checked into version control, are no longer static documents. They become active @@ -1068,6 +1071,9 @@ aligned with what is needed. accessed on 14 July 2025, +[^4]: Gherkin Syntax in Cucumber — Tutorialspoint, accessed on 14 July 2025, + + [^5]: *Given When Then* — Martin Fowler, accessed on 14 July 2025, @@ -1078,9 +1084,15 @@ aligned with what is needed. [^7]: *Reference — Cucumber*, accessed on 14 July 2025, +[^8]: BDD (Behavior Driven Development) — ROBOT FRAMEWORK, accessed on 14 July + 2025, + [^9]: Given-When-Then - Wikipedia, accessed on 14 July 2025, +[^10]: When to Use "Given-When-Then" Acceptance Criteria — Ranorex, accessed on + 14 July 2025, + [^11]: *Writing scenarios with Gherkin syntax* — CucumberStudio Documentation, accessed on 14 July 2025, @@ -1095,15 +1107,19 @@ aligned with what is needed. external test runners or dependencies. GitHub, accessed on 14 July 2025, + runners or dependencies. - GitHub, accessed on 14 July 2025, + + [^16]: cucumber - Rust - [Docs.rs](http://Docs.rs), accessed on 14 July 2025, + 2025, + [^18]: *Quickstart* — Cucumber Rust Book, accessed on 14 July 2025, -[^19]: *A Beginner’s Guide to Cucumber in Rust* — Florian Reinhard, accessed - on 14 July 2025, - + 14 July 2025, + [^20]: Quickstart - Cucumber Rust Book, accessed on 14 July 2025, @@ -1116,10 +1132,15 @@ aligned with what is needed. Stack Overflow, accessed on 14 July 2025, -[^23]: Data tables - Cucumber Rust Book, accessed on 14 July 2025, +[^23]: Data tables - Cucumber Rust Book, accessed on 14 July 2025, -[^25]: Best practices for scenario writing | CucumberStudio Documentation +[^24]: Cucumber Data Tables — Tutorialspoint, accessed on 14 July 2025, + + +[^25]: Best practices for scenario writing — CucumberStudio Documentation, + accessed on 14 July 2025, + [^26]: Cucumber Best Practices to follow for efficient BDD Testing | by KailashPathak - Medium, accessed on 14 July 2025, @@ -1128,12 +1149,21 @@ aligned with what is needed. [^27]: Rust Solutions - WireMock, accessed on 14 July 2025, +[^28]: Unit-testing a web service in Rust — Julio Merino (jmmv.dev), accessed + on 14 July 2025, + + +[^29]: Cucumber Best Practices for Effective BDD Testing — BrowserStack, + accessed on 14 July 2025, + + [^30]: Common Challenges in Cucumber Testing and How to Overcome Them - Medium, accessed on July 14, 2025, [^31]: Cucumber in cucumber - Rust - [Docs.rs](http://Docs.rs), accessed on - 14 July 2025, + 14 July 2025, + [^32]: CLI (command-line interface) - Cucumber Rust Book, accessed on 14 July 2025, @@ -1141,6 +1171,9 @@ aligned with what is needed. [^33]: Continuous Integration - Cucumber, accessed on 14 July 2025, +[^34]: GitLab CI/CD examples, accessed on 14 July 2025, + + [^35]: Setting up effective CI/CD for Rust projects - a short primer - [shuttle.dev](http://shuttle.dev), accessed on 14 July 2025,