inholland/ros2-assignments
3
1
Fork 0
generated from wessel/boilerplate
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Update documentation for new assignment

Browse Source
This commit is contained in:
Wessel T
2025-11-03 11:36:14 +01:00
parent f07a196f92
commit 645a5d0107
14 changed files with 32 additions and 826 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
doc/tests/ExamResultGenerator.md
View File

@@ -1,62 +0,0 @@
# Exam Result Generator Node Unit Tests
Unit tests for `ExamResultGenerator` are implemented in `src/g2_2025_grade_calculator_pkg/test/ExamResultGenerator.test.cpp` using Google Test and ROS2 test utilities. The tests use a test subscriber node to capture published messages and validate node behavior.
## Test Cases
### 1. ConstructorTest
**Description:** Verifies that ExamResultGenerator can be created without crashing and proper initialization occurs.
- **Test Action:** Create ExamResultGenerator node instance
- **Expected Result:**
- Node created successfully without exceptions
- Node name set to `"exam_result_generator"`
### 2. PublisherCreationTest
**Description:** Verifies that the `exam_results` topic publisher is properly configured.
- **Test Action:** Check topic names and types after node creation
- **Expected Result:**
- `/exam_results` topic is published
- Topic uses `g2_2025_interfaces/msg/Exam` message type
### 3. SubscriberCreationTest
**Description:** Tests that the node subscribes to the `student_course_management` topic with correct message type.
- **Test Action:** Check subscription topics and types
- **Expected Result:**
- `/student_course_management` topic is subscribed
- Subscription uses `g2_2025_interfaces/msg/Student` message type
### 4. StudentManagementMessageHandlingTest
**Description:** Tests the node's ability to handle incoming student management messages without crashing.
- **Test Action:**
- Publish student management message:
- Student: `"Test Student"`
- Course: `"Test Course"`
- **Expected Result:** Message processed without crashes
### 5. MultipleStudentMessagesTest
**Description:** Validates handling of multiple rapid student management messages for robustness testing.
- **Test Action:**
- Send multiple messages with different student-course combinations
- Students: `["Alice", "Bob", "Charlie"]`
- Courses: `["Math", "Physics", "Chemistry"]`
- **Expected Result:** All messages processed without crashes or memory issues
### 6. ExamMessageValidationTest
**Description:** Captures and validates published exam result messages for correct content and format.
- **Test Action:** Listen for published exam result messages over 6 seconds
- **Expected Result:**
- Published grades are within range `[10, 100]`
- Course names are not empty
- Message format is correct

52
doc/tests/FinalGradeDeterminator.md
View File

@@ -1,52 +0,0 @@
# Final Grade Determintator Node Unit Tests
Unit tests for `FinalGradeDeterminator` are implemented in `src/g2_2025_grade_calculator_pkg/test/FinalGradeDeterminator.test.cpp` using Google Test and ROS2 test utilities. The tests use a mock database manager and a mock grade calculator service to simulate the node's interactions.
## Test Cases
### 1. ConstructorTest
**Description:** Verifies that the node can be constructed without errors.
- **Input:** Construct a `FinalGradeDeterminator` node.
- **Expected Output:** No exceptions are thrown. The node is created successfully.
### 2. ExamCollectionTest
**Description:** Sends the required number of exam results and checks that a grade calculation request is triggered, a student message is published, and the results are stored.
- **Input:**
- Student: `"Test Student"`
- Course: `"Test Course"`
- Grades published: `[80, 85, 90, 75, 95]` (5 exam results, which is the default required amount)
- **Expected Output:**
- A grade calculation service request is made with the correct student, course, and grades.
- A student message is published with the correct student and course.
- The final grade is calculated as the average: (80 + 85 + 90 + 75 + 95) / 5 = 85.
### 3. PartialExamCollectionTest
**Description:** Sends fewer than the required number of exam results and checks that no grade calculation or student message occurs.
- **Input:**
- Student: `"Test Student"`
- Course: `"Test Course"`
- Grades published: `[80, 85, 90]` (only 3 exam results, less than required)
- **Expected Output:**
- No grade calculation service request is made.
- No student message is published.
### 4. MultipleStudentsTest
**Description:** Simulates multiple students submitting exam results and verifies that each student triggers independent grade calculation and messaging.
- **Input:**
- Students: `"Alice"`, `"Bob"`
- Course: `"Test Course"`
- Each student receives grades: `[80, 85, 90, 75, 95]` (5 exam results per student)
- **Expected Output:**
- Two grade calculation service requests are made, one for each student, with the correct grades.
- Two student messages are published, one for each student.
- The final grade for each student is calculated as the average: (80 + 85 + 90 + 75 + 95) / 5 = 85.
These tests ensure that the node correctly collects exam results, triggers grade calculation at the right time, publishes the appropriate messages, and interacts with the database as expected.

56
doc/tests/GradeCalculator.md
View File

@@ -1,56 +0,0 @@
# Grade Calculator Node Unit Tests
Unit tests for `GradeCalculator` are implemented in `src/g2_2025_grade_calculator_pkg/test/GradeCalculator.test.cpp` using Google Test and ROS2 test utilities. The tests use a client to call the grade calculation service and verify the results.
## Test Cases
### 1. NormalAverage
**Description:** Verifies that the service returns the average of the provided grades for a normal student name.
- **Input:**
- Student: `"Alice"`
- Grades: `[80, 90, 70]`
- **Expected Output:**
- Result: `80` (average of 80, 90, 70)
### 2. WesselBonus
**Description:** Checks that the student name "Wessel" (case-insensitive) receives a 10-point bonus, and the result is clamped to 100 if necessary.
- **Input:**
- Student: `"Wessel"`
- Grades: `[80, 90, 70]`
- **Expected Output:**
- Result: `90` (average 80 + 10 bonus)
#### 3. wesselBonus
**Description:** Checks that the bonus logic is case-insensitive for the student name "wessel".
- **Input:**
- Student: `"wessel"`
- Grades: `[80, 90, 70]`
- **Expected Output:**
- Result: `90` (average 80 + 10 bonus)
#### 4. GradeTooHigh
**Description:** Ensures that the grade is clamped to a maximum of 100, even after applying the bonus.
- **Input:**
- Student: `"Wessel"`
- Grades: `[100, 100, 100]`
- **Expected Output:**
- Result: `100` (average 100 + 10 bonus, clamped to 100)
#### 5. GradeTooLow
**Description:** Ensures that the grade is clamped to a minimum of 10.
- **Input:**
- Student: `"Alice"`
- Grades: `[0, 0, 0]`
- **Expected Output:**
- Result: `10` (average 0, clamped to 10)

151
doc/tests/IntegrationTest.md
View File

@@ -1,151 +0,0 @@
# Integration Test
Tests the whole integrated system `nodes` connected with each other, with supervisory control and visualization of the database. It tests all major components working together: exam result generation, calculation, database usage, and retake handling.
For validation and verification of database data the databse viewer Dbeaver can be used.
## Test Input Data
**Student Enrollments:**
- `"Wessel", "ROS2"`
- `"Vincent", "ROS2"`
- `"Mohammed", "Differentieren"`
- `"Tilmann", "Differentieren"`
## Test workflow
### 1. Complete Grade Processing Pipeline
**Description**: Tests the full workflow from student enrollment through exam generation to final grade calculation.
**Steps:**
1. **Setup Phase**
- Clear the database via `docker container prune` or by deleting the tables in dbeaver.
- Start the databse in a standalone terminal via the command `sudo docker compose up`.
- Verify database connection.
- Initialize all system nodes (ExamResultGenerator, FinalGradeDeterminator, GradeCalculator) after building tha package and starting it via the `grade_calculator.launch.xml`.
2. **Exam Generation Phase**
- ExamResultGenerator publishes Exam messages per student-course pair to table `exam_results` topic.
- Verify exam results have valid grades (10-100 range).
- Confirm proper timestamp and student/course name matching.
3. **Grade Collection Phase**
- FinalGradeDeterminator collects exam results for each student-course combination.
- Monitor collection count reaches threshold (5 exams per student-course by default) for each student.
4. **Grade Calculation Phase**
- FinalGradeDeterminator calls GradeCalculator service when threshold reached.
- Service calculates average grade.
5. **Persistence and Notification Phase**
- Final grades stored in database with proper timestamps.
- verify that final_grade_determinator has sent a de-enroll request via student_course_managment to exam_result_generator.
- exam_result_generator should now prints `removed from queue`.
- Verify final grade is within valid bounds (10-100) in table `final_course_results`.
**Expected Results:**
```text
Student: Wessel, Course: ROS2
- 5 exam results generated (random grades 10-100)
- Avrage final grade calculated
- Grade stored in database
Student: Vincent, Course: ROS2
- 5 exam results generated (random grades 10-100)
- Avrage final grade calculated
- Grade stored in database
Student: Mohammed, Course: Differentieren
- 5 exam results generated (random grades 10-100)
- Avrage final grade calculated
- Grade stored in database
Student: Tilmann, Course: Differentieren
- 5 exam results generated (random grades 10-100)
- Avrage final grade calculated
- Grade stored in database
```
### 2. Retake Process Integration
**Description**: Tests the retake workflow for students who need to retake exams.
**Setup:**
no setup required, this starts immediately after `final_grade_diterminator` is done after getting the first grades for the students.
**Steps:**
1. **Varify Retake Schedualer is started**
- Verify in the terminal the schedualer starts the retake process.
2. **Retake Request Phase**
- RetakeScheduler checks the database for failing students
- Schedules retake exams with `retake_grade_determinator`
3. **Retake Execution Phase**
- Generate retake exam results
- `retake_grade_determinator` processes retake grades and sends them to the calcculator.
- `retake_grade_determinator` finaly stores the calculated result in the database.
4. **Final Grade Update**
- Verify grade history preservation
- Confirm final grade reflects retake performance
**Failing student Expected Retake Results:**
```text
Student: student, Course: course
- 5 exam results generated (random grades 10-100)
- Avrage final grade calculated
- Grade stored in database
- Retake_done checkmark
- Is_retake checkmark
```
## Success Criteria
### Functional Requirements
All student enrollments processed correctly
Exam results generated within valid range (10-100)
Grade collection reaches configured thresholds
Final grades calculated using proper business logic
Database persistence works reliably
Retake process functions correctly when needed
All ROS2 communication protocols working
## Test Execution Commands
```bash
# 1. enter the ros2 assignment folder
cd /YOUR/PATH/HERE/ros2-assignment
# 2. Build the packages and source the enviroment
colcon build && source install/setup.bash
# 3. clear and Start database (if not running) in stand alone terminal
sudo docker container prune && sudo docker compose up
# 4. Launch all system nodes
ros2 launch g2_2025_grade_calculator_pkg grade_calculator.launch.xml
# 6. Monitor database state
By opening dbeaver and connecting to the database "grades".
Password: postgres
```
## Verification
### Database Validation
- **Student Records**: Verify all students are enrolled correctly
- **Exam Results**: Confirm all exam data is good
- **Final Grades**: Validate calculated grades and timestamps

70
doc/tests/RetakeGradeDeterminator.md
View File

@@ -1,70 +0,0 @@
# RetakeGradeDeterminator Node Unit Tests
This document describes the unit tests for the `RetakeGradeDeterminator` ROS 2 node, as implemented in [`RetakeGradeDeterminator.test.cpp`](../../src/g2_2025_grade_calculator_pkg/test/RetakeGradeDeterminator.test.cpp).
## Test Cases
### 1. ConstructorTest
- **Purpose:**
Verifies that the `RetakeGradeDeterminator` can be constructed without throwing exceptions.
- **Checks:**
- The node is created successfully and is not `nullptr`.
### 2. PublisherCreationTest
- **Purpose:**
Ensures that the node creates a publisher for the `student_course_management` topic.
- **Checks:**
- The `/student_course_management` topic is present and uses the `Student` message type.
### 3. SubscriberCreationTest
- **Purpose:**
Ensures that the node subscribes to the `exam_results` topic.
- **Checks:**
- The `/exam_results` topic is present and uses the `Exam` message type.
### 4. ActionServerCreationTest
- **Purpose:**
Verifies that the node creates an action server for the `retake_action`.
- **Checks:**
- The action server is available and can be connected to by an action client.
### 5. ServiceClientCreationTest
- **Purpose:**
Ensures that the node creates a client for the `grade_calculator_service`.
- **Checks:**
- The `/grade_calculator_service` is present in the node's service graph.
### 6. ParameterTest
- **Purpose:**
Confirms that the node's parameters are set to their expected default values.
- **Checks:**
- The `grade_collection_amount` parameter defaults to `5`.
### 7. ExamResultsIgnoredWhenRetakeNotAllowed
- **Purpose:**
Ensures that exam results are ignored if a retake is not currently allowed.
- **Checks:**
- No service requests are made when a retake is not in progress.
### 8. RetakeActionGoalAcceptance
- **Purpose:**
Verifies that the node accepts retake action goals and publishes the appropriate student enrollment message.
- **Checks:**
- The retake goal is accepted.
- A `Student` message is published with the correct student and course names.
### 9. PartialExamResultsCollection
- **Purpose:**
Ensures that the node does not process or store results if not enough exam results have been collected during a retake.
- **Checks:**
- No service requests are made.
- No results are stored in the database if the required number of exam results has not been reached.

50
doc/tests/RetakeScheduler.md
View File

@@ -1,50 +0,0 @@
# RetakeScheduler Node Unit Tests
Unit tests for `RetakeScheduler` are implemented in `src/g2_2025_grade_calculator_pkg/test/RetakeScheduler.test.cpp`
The unit tests are written using Google Test and ROS 2 test utilities. They utilize clients to interact
with the RetakeScheduler node's services and actions, verifying correct behavior and expected outcomes.
## Test Cases
### 1. ConstructorTest
- **Purpose:**
Verifies that the `RetakeScheduler` can be constructed without throwing exceptions.
- **Checks:**
- The node is created successfully and is not `nullptr`.
### 2. ActionClientCreationTest
- **Purpose:**
Ensures that the `RetakeScheduler` node creates the expected action client services for the retake action.
- **Checks:**
- At least one of the retake action client services (`/retake_action/_action/cancel_goal`, `/retake_action/_action/get_result`, `/retake_action/_action/send_goal`) is present in the node's service graph.
### 3. ParameterTest
- **Purpose:**
Confirms that the node's parameters are set to their expected default values.
- **Checks:**
- The `retake_check_interval_sec` parameter defaults to `120`.
### 4. ActionClientAllServicesPresentTest
- **Purpose:**
Verifies that all required action client services for the retake action are available.
- **Checks:**
- The following services are present:
- `/retake_action/_action/cancel_goal`
- `/retake_action/_action/get_result`
- `/retake_action/_action/send_goal`
### 5. ConstructorWithNullDatabaseManager
- **Purpose:**
Tests the node's behavior when constructed with a `nullptr` database manager.
- **Checks:**
- The node can be constructed without throwing, even if the database manager is `nullptr`.