From ecedd380cc00500bf942717c38db7bca218c189a Mon Sep 17 00:00:00 2001 From: Jimisola Laursen Date: Sat, 7 Mar 2026 23:03:34 +0100 Subject: [PATCH] docs: rename requirement IDs to descriptive names and add missing test scenario Rename all requirement IDs from generic (REQ_010, etc.) to descriptive names (REQ_PASS, REQ_FAILING_TEST, etc.) that reflect the scenario each demonstrates. Add REQ_MISSING_TEST scenario showing an SVC with no corresponding test, and flesh out all demo code with real implementations. Signed-off-by: jimisola --- README.md | 13 +++++ docs/reqstool/manual_verification_results.yml | 3 +- docs/reqstool/requirements.yml | 49 +++++++++++++------ docs/reqstool/software_verification_cases.yml | 38 ++++++++++---- .../example/demo/DemoApplication.java | 4 +- .../example/demo/RequirementsExample.java | 32 +++++++++--- .../example/demo/DemoApplicationTestsIT.java | 9 ++-- .../reqstool/example/demo/SVCsTest.java | 39 ++++++++++++--- 8 files changed, 141 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index 2e18796..b613726 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,19 @@ This project demonstrates: - Integration with the reqstool Python client for requirements analysis - Support for both Maven and Gradle build systems +## Demo Scenarios + +Each requirement ID is named to reflect the scenario it demonstrates: + +| Requirement ID | Scenario | What it demonstrates | +|---|---|---| +| `REQ_PASS` | Fully implemented & verified | Code annotated, automated tests pass, manual verification passes | +| `REQ_MANUAL_FAIL` | Manual verification failed | Code annotated, automated tests pass, but manual verification reports a failure | +| `REQ_NOT_IMPLEMENTED` | Not implemented | Requirement defined but no `@Requirements` annotation in code | +| `REQ_FAILING_TEST` | Automated test fails | Code annotated, but the implementation has a bug causing the test to fail | +| `REQ_SKIPPED_TEST` | Test is skipped | Code annotated, but the test is `@Disabled` (e.g. pending integration) | +| `REQ_MISSING_TEST` | Test not written | Code annotated, SVC defined, but no `@SVCs` test exists for the SVC | + ## Prerequisites - Java 21+ diff --git a/docs/reqstool/manual_verification_results.yml b/docs/reqstool/manual_verification_results.yml index 37aaf68..0686923 100644 --- a/docs/reqstool/manual_verification_results.yml +++ b/docs/reqstool/manual_verification_results.yml @@ -3,9 +3,10 @@ results: - id: MVR_201 svc_ids: ["SVC_021"] + comment: Greeting message correctly displayed with user's name in the UI header. pass: true - id: MVR_202 svc_ids: ["SVC_022"] - comment: Failed due... + comment: Failed due to rounding error - total shows 9.99 instead of 10.00 for 2x5.00 items. pass: false diff --git a/docs/reqstool/requirements.yml b/docs/reqstool/requirements.yml index f0fe2f7..f6d8bd7 100644 --- a/docs/reqstool/requirements.yml +++ b/docs/reqstool/requirements.yml @@ -12,24 +12,45 @@ metadata: # - path: ./ext-001 requirements: - - id: REQ_010 - title: Title REQ_010 - significance: may - description: Description REQ_010 - rationale: Rationale REQ_010 + - id: REQ_PASS + title: Display greeting message + significance: shall + description: The system shall display a personalized greeting message based on a given name parameter. + rationale: Users need to receive a personalized greeting to confirm their identity when interacting with the system. categories: ["functional-suitability", "maintainability"] revision: 0.0.1 - - id: REQ_020 - title: Title REQ_020 - significance: may - description: Description REQ_020 - rationale: Rationale REQ_020 + - id: REQ_MANUAL_FAIL + title: Calculate item total + significance: shall + description: The system shall calculate the total price for a given quantity of items. + rationale: Accurate price calculation is essential for correct billing and invoicing. categories: ["functional-suitability", "maintainability"] revision: 0.0.1 - - id: REQ_030 - title: Title REQ_030 + - id: REQ_NOT_IMPLEMENTED + title: Export report as PDF significance: may - description: Description REQ_030 - rationale: Rationale REQ_030 + description: The system should support exporting reports in PDF format. + rationale: PDF export enables users to share and archive reports in a portable format. categories: ["functional-suitability", "maintainability"] revision: 0.0.1 + - id: REQ_FAILING_TEST + title: Validate email format + significance: shall + description: The system shall validate that a provided email address conforms to standard email format. + rationale: Ensuring valid email format prevents delivery failures and improves data quality. + categories: ["functional-suitability"] + revision: 0.0.1 + - id: REQ_SKIPPED_TEST + title: Send notification via SMS + significance: may + description: The system should support sending notifications to users via SMS. + rationale: SMS notifications provide an alternative channel for time-sensitive alerts. + categories: ["functional-suitability"] + revision: 0.0.1 + - id: REQ_MISSING_TEST + title: Generate audit log entry + significance: shall + description: The system shall generate an audit log entry for each user action. + rationale: Audit logging is required for compliance and security traceability. + categories: ["functional-suitability"] + revision: 0.0.1 diff --git a/docs/reqstool/software_verification_cases.yml b/docs/reqstool/software_verification_cases.yml index c31f75e..a264d5a 100644 --- a/docs/reqstool/software_verification_cases.yml +++ b/docs/reqstool/software_verification_cases.yml @@ -2,31 +2,49 @@ cases: - id: SVC_010 - requirement_ids: ["REQ_010"] - title: "Some Title SVC_010" + requirement_ids: ["REQ_PASS"] + title: "Verify greeting message contains the provided name" verification: automated-test revision: "0.0.1" - id: SVC_020 - requirement_ids: ["REQ_020"] - title: "Some Title SVC_102" + requirement_ids: ["REQ_MANUAL_FAIL"] + title: "Verify total price calculation for given quantity" verification: automated-test revision: "0.0.1" - id: SVC_021 - requirement_ids: ["REQ_010"] - title: "Some Title SVC_021" + requirement_ids: ["REQ_PASS"] + title: "Manually verify greeting is displayed correctly in UI" verification: manual-test revision: "0.0.1" - id: SVC_022 - requirement_ids: ["REQ_020"] - title: "Some Title SVC_022" + requirement_ids: ["REQ_MANUAL_FAIL"] + title: "Manually verify total price is shown on invoice page" verification: manual-test revision: "0.0.1" - id: SVC_030 - requirement_ids: ["REQ_030"] - title: "Some Title SVC_030" + requirement_ids: ["REQ_NOT_IMPLEMENTED"] + title: "Verify PDF export produces a valid document" + verification: automated-test + revision: "0.0.1" + + - id: SVC_040 + requirement_ids: ["REQ_FAILING_TEST"] + title: "Verify email validation rejects invalid formats" + verification: automated-test + revision: "0.0.1" + + - id: SVC_050 + requirement_ids: ["REQ_SKIPPED_TEST"] + title: "Verify SMS notification is sent successfully" + verification: automated-test + revision: "0.0.1" + + - id: SVC_060 + requirement_ids: ["REQ_MISSING_TEST"] + title: "Verify audit log entry is created for user actions" verification: automated-test revision: "0.0.1" diff --git a/src/main/java/io/github/reqstool/example/demo/DemoApplication.java b/src/main/java/io/github/reqstool/example/demo/DemoApplication.java index fd568fc..1c0b60a 100644 --- a/src/main/java/io/github/reqstool/example/demo/DemoApplication.java +++ b/src/main/java/io/github/reqstool/example/demo/DemoApplication.java @@ -4,8 +4,8 @@ public class DemoApplication { public static void main(String[] args) { RequirementsExample example = new RequirementsExample(); - example.firstMethod(10); - example.someMethod(15); + System.out.println(example.greet("World")); + System.out.println(example.calculateTotal(3, 9.99)); } } diff --git a/src/main/java/io/github/reqstool/example/demo/RequirementsExample.java b/src/main/java/io/github/reqstool/example/demo/RequirementsExample.java index 66be611..64a9c52 100644 --- a/src/main/java/io/github/reqstool/example/demo/RequirementsExample.java +++ b/src/main/java/io/github/reqstool/example/demo/RequirementsExample.java @@ -2,17 +2,35 @@ import io.github.reqstool.annotations.Requirements; -@Requirements({ "REQ_010", "REQ_020" }) +@Requirements({ "REQ_PASS", "REQ_MANUAL_FAIL", "REQ_FAILING_TEST", "REQ_SKIPPED_TEST", "REQ_MISSING_TEST" }) public class RequirementsExample { - @Requirements({ "REQ_010" }) - public void firstMethod(float parameter) { - System.out.println("This is a parameter:" + parameter); + @Requirements({ "REQ_PASS" }) + public String greet(String name) { + return "Hello, " + name + "!"; } - @Requirements("REQ_020") - public void someMethod(int parameter) { - System.out.println("This is another parameter: " + parameter); + @Requirements("REQ_MANUAL_FAIL") + public double calculateTotal(int quantity, double unitPrice) { + return quantity * unitPrice; + } + + @Requirements("REQ_FAILING_TEST") + public boolean isValidEmail(String email) { + // Bug: missing check for domain part - will cause test failure + return email != null && email.contains("@"); + } + + @Requirements("REQ_SKIPPED_TEST") + public boolean sendSms(String phoneNumber, String message) { + // TODO: SMS gateway integration not yet available + throw new UnsupportedOperationException("SMS gateway not yet integrated"); + } + + @Requirements("REQ_MISSING_TEST") + public void auditLog(String userId, String action) { + // Audit log implementation + System.out.println("Audit: user=" + userId + " action=" + action); } } diff --git a/src/test/java/io/github/reqstool/example/demo/DemoApplicationTestsIT.java b/src/test/java/io/github/reqstool/example/demo/DemoApplicationTestsIT.java index d7160cc..f2d1490 100644 --- a/src/test/java/io/github/reqstool/example/demo/DemoApplicationTestsIT.java +++ b/src/test/java/io/github/reqstool/example/demo/DemoApplicationTestsIT.java @@ -1,6 +1,6 @@ package io.github.reqstool.example.demo; -import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.junit.jupiter.api.Assertions.assertNotNull; import org.junit.jupiter.api.Test; @@ -10,9 +10,10 @@ class DemoApplicationTestsIT { @Test @SVCs("SVC_010") - @java.lang.SuppressWarnings("java:S2701") - void contextLoads() { - assertTrue(true, "dummy test"); + void shouldGreetWithNonNullResult() { + RequirementsExample example = new RequirementsExample(); + String result = example.greet("Integration"); + assertNotNull(result); } } diff --git a/src/test/java/io/github/reqstool/example/demo/SVCsTest.java b/src/test/java/io/github/reqstool/example/demo/SVCsTest.java index aff38c8..a2ce621 100644 --- a/src/test/java/io/github/reqstool/example/demo/SVCsTest.java +++ b/src/test/java/io/github/reqstool/example/demo/SVCsTest.java @@ -1,7 +1,10 @@ package io.github.reqstool.example.demo; +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; import static org.junit.jupiter.api.Assertions.assertTrue; +import org.junit.jupiter.api.Disabled; import org.junit.jupiter.api.Test; import io.github.reqstool.annotations.SVCs; @@ -10,23 +13,43 @@ public class SVCsTest { @Test @SVCs("SVC_010") - @java.lang.SuppressWarnings("java:S2701") - public void testMethod1() { - assertTrue(false, "dummy test"); + public void shouldReturnGreetingWithName() { + RequirementsExample example = new RequirementsExample(); + String result = example.greet("World"); + assertEquals("Hello, World!", result); } @Test @SVCs("SVC_020") - @java.lang.SuppressWarnings("java:S2701") - public void testMethod2() { - assertTrue(true, "dummy test"); + public void shouldCalculateTotalCorrectly() { + RequirementsExample example = new RequirementsExample(); + double result = example.calculateTotal(3, 5.0); + assertEquals(15.0, result); } @Test @SVCs("SVC_030") @java.lang.SuppressWarnings("java:S2701") - public void testMethod3() { - assertTrue(true, "dummy test"); + public void shouldExportReportAsPdf() { + // Not yet implemented - placeholder test + assertTrue(true, "PDF export not yet implemented"); + } + + @Test + @SVCs("SVC_040") + public void shouldRejectInvalidEmailFormat() { + RequirementsExample example = new RequirementsExample(); + // This will fail because isValidEmail only checks for '@', not domain format + assertFalse(example.isValidEmail("user@"), "Email without domain should be invalid"); + } + + @Test + @SVCs("SVC_050") + @Disabled("SMS gateway integration not yet available") + public void shouldSendSmsNotification() { + RequirementsExample example = new RequirementsExample(); + boolean result = example.sendSms("+1234567890", "Test notification"); + assertTrue(result); } }