From 15df68d9da1f512c4ef7de144d09d105c546181b Mon Sep 17 00:00:00 2001
From: LolloBici <lorenzo.amici@skywarder.eu>
Date: Thu, 28 Nov 2024 00:58:07 +0100
Subject: [PATCH] [unit-test][UnitTest] Documentation update
---
unitTests/README.md | 129 +++++++++++++++++++++++++++++++-------------
1 file changed, 92 insertions(+), 37 deletions(-)
diff --git a/unitTests/README.md b/unitTests/README.md
index 1f359d44..dba971d1 100644
--- a/unitTests/README.md
+++ b/unitTests/README.md
@@ -1,51 +1,102 @@
-# Unit Testing Framework for msa-toolkit
+# 📘 **Unit Test Documentation**
-This repository provides a unit testing framework designed to validate key functionalities for some tools of the msa-toolkit.
-It includes various test classes, scripts for configuration and execution, and a `data` folder containing reference data and inputs for the tests.
+This repository provides a robust **unit testing framework** to validate key tools of the `msa-toolkit`. It ensures **consistency**, **reliability**, and the **correctness of computations**.
---
-## **Folder Structure**
+## 📂 **Folder Structure**
### **Key Components**
-- **`data/`**: Stores all reference data and input files needed for the tests.
-- **Test Classes**: Each class (e.g., `TestCommonFunctions`, `TestSimulator`).
-- **Scripts**:
- - **`mainUnitTest.m`**: Executes the selected tests based on the configuration.
- - **`saveTests.m`**: Saves settings and reference data for future tests.
- - **`configUnitTest.m`**: Allows users to configure which tests to run or save, as well as the mission parameters.
+- 📁 **`data`**:
+ Contains all **reference data** and **input files** required to run the tests.
+ Includes pre-configured mission settings and references.
+
+- 📁 **`tests`**:
+ Houses the test classes. Each class targets a specific functionality of the toolkit:
+ - **`TestCommonFunctions`**
+ - **`TestSimulator`**
+ - **`TestApogeeAnalysis`**
+ - **`TestSensitivity`**
+ - **`TestOptimization`**
+
+- 📝 **Scripts**:
+ - **`mainUnitTest.m`**: Runs the tests selected in `configUnitTest.m`.
+ - **`saveTests.m`**: Generates and saves test settings along with reference data.
+ - **`configUnitTest.m`**: Lets users configure which tests to execute or save and specify the mission instance for the test.
---
-## **How to Run Tests**
+## 🚀 **How to Run Tests**
+
+### 1️⃣ **Automatic Testing**
+Tests are executed automatically when merging a branch into the `main` branch to ensure the robustness of new changes.
+
+### 2️⃣ **Manual Testing**
+
+#### ⚙️ **Step 1: Configure Tests**
+- Open the `configUnitTest.m` script.
+ - Enable the desired tests in the configuration as shown in the following example:
+ ```matlab
+ opt.testSimulator = true;
+ ```
+
+ - Define mission istance as shown in the following example:
+ ```
+ mission = Mission("2025_Orion_Roccaraso_September")
+ ```
+
+#### ▶️ **Step 2: Run Tests**:
+ - Execute the `mainUnitTest.m` script. This will run all the tests specified in the `configUnitTest.m`.
+
+#### 📊 **Output**:
+
+ The output of the `mainUnitTest` provides detailed information about the execution of each test. The results are categorized as follows:
-### 1. **Automatic Testing**
-Tests are executed automatically when merging a branch into the `main` branch.
-This ensures all functionalities are validated before the merge.
+- ✅ **Successful Tests**:
+ The output explicitly states that the test was executed and completed successfully.
-### 2. **Manual Testing**
-To run tests manually:
-1. **Configure Tests**: Open the `configUnitTest.m` script and specify:
- - The tests to be executed.
- - The mission parameters for the tests.
-2. **Run the Tests**: Execute the `mainUnitTest.m` script:
+- ❌ **Failed Tests**:
+ For tests that fail, the output identifies:
+ - The values that are not equal.
+ - The **absolute error** between the expected and actual values.
+ - The **relative error**, highlighting the difference in relation to the expected value.
+
+- ⚠️ **Incomplete Tests**:
+ If a test is incomplete, the output specifies:
+ - The exact point where the test stopped execution.
+ - Any relevant context or partial results to assist in debugging.
---
-## **How to Save Tests**
-
-### 2. **Manual Testing**
-1. **Configure Tests**: Open the `configUnitTest.m` script and specify:
- - The tests to be saved.
- - The mission parameters for the tests.
-2. **Save the Tests**: Execute the `saveTests.m` script:
- - For `TestSimulator`, you need to add a verifiable string (e.g. `verifiable = 'HRE'`).
- - For `TestCommonFunction`, it is necessary to define several key variables
- that are essential for the test setup. These variables include `vars`, `t`,
- `alpha`, `mach`, `beta`, `alt` and `c`
- (e.g.
-```
-vars.mach = 0.05:0.05:1;
+## 💾 **How to Save Tests**
+
+### 📝 **Overview**
+The `saveTests.m` script allows users to generate and save test reference data. This feature is crucial for validating future changes by comparing against pre-saved data.
+
+### 🛠 **Steps to Save Tests**
+
+#### ⚙️ **Step 1: Configure the Test Settings**:
+ - Open the `configUnitTest.m` script and specify the tests to save:
+ - Enable the test type (e.g., `opt.createTestSimulator = true`).
+ - Define the mission istance (e.g. `mission = Mission("2025_Orion_Roccaraso_September")`).
+
+#### 💾 **Step 2: Save Test Data**:
+ - Run the `saveTests.m` script:
+ - > [!NOTE]
+ For **`TestSimulator`**, define a verifiable string and execute the saving routine as shown in the following example:
+ ```MATLAB
+ if opt.createTestSimulator
+ verifiable = 'HRE';
+ TestSimulator.saveTest(verifiable, mission);
+ end
+ ```
+
+ - > [!NOTE]
+ For **`TestCommonFunctions`**, configure key parameters as shown in the following example:
+
+ ```matlab
+ if opt.createTestCommonFunction
+ vars.mach = 0.05:0.05:1;
vars.alpha = [-10 -7.5 -5 -2.5 -1 -0.5 -0.1 0 0.1 0.5 1 2.5 5 7.5 10];
vars.beta = [-2.5 -0.1 0 0.1 2.5];
vars.alt = (0:400:4000);
@@ -56,6 +107,10 @@ vars.mach = 0.05:0.05:1;
beta = 2;
alt = 1145;
c = 2;
-```
- ).
-
+ TestCommonFunctions.saveTest(mission, vars, t, alpha, mach, beta, alt, c);
+ end
+ ````
+
+#### ✅ **Step 3:Verify Test Saving**:
+ - Check in the `data` folder
+if the references are saved correctly.
\ No newline at end of file
--
GitLab