From 5b8d66bbacadf4feac2b2bdf23f28f7a41898679 Mon Sep 17 00:00:00 2001
From: Robert Schmidt <robert.schmidt@openairinterface.org>
Date: Thu, 7 Aug 2025 18:15:26 +0200
Subject: [PATCH] Write simple CI documentation and add sample script

---
 ci-scripts/README.md                          | 60 ++++++++++++
 .../xml_files/container_5g_rfsim_simple.xml   | 97 +++++++++++++++++++
 doc/README.md                                 |  2 +
 3 files changed, 159 insertions(+)
 create mode 100644 ci-scripts/README.md
 create mode 100644 ci-scripts/xml_files/container_5g_rfsim_simple.xml

diff --git a/ci-scripts/README.md b/ci-scripts/README.md
new file mode 100644
index 0000000000..becd518e4c
--- /dev/null
+++ b/ci-scripts/README.md
@@ -0,0 +1,60 @@
+This document outlines how to use the OAI CI framework and gives a quickstart.
+
+[[_TOC_]]
+
+# Quickstart
+
+There is a script `main.py` that
+
+- reads scenario files from XML
+- executes the steps (e.g., deployment of CN/gNB/UE, attach, ping, ...)
+
+To simplify, a script `run_locally.sh` can be used to run a single scenario
+locally.  First, download images for gNB&UE (we assume you already downloaded
+the CN) and tag them "latest", which is expected by `run_locally.sh`:
+
+    docker pull oaisoftwarealliance/oai-gnb:develop
+    docker tag oaisoftwarealliance/oai-gnb:develop oai-gnb
+    docker pull oaisoftwarealliance/oai-nr-ue:develop
+    docker tag oaisoftwarealliance/oai-nr-ue:develop oai-nr-ue
+
+Now, run the scenario:
+
+    cd ~/openairinterface5g/ci-scripts/
+    ./run_locally.sh xml_files/container_5g_rfsim_simple.xml
+
+Output should look like
+
+```
+[2025-08-07 18:07:49,631]     INFO: ----------------------------------------
+[2025-08-07 18:07:49,631]     INFO:   Creating HTML header 
+[2025-08-07 18:07:49,631]     INFO: ----------------------------------------
+[2025-08-07 18:07:49,766]     INFO: ----------------------------------------
+[2025-08-07 18:07:49,767]     INFO:   Starting Scenario: xml_files/container_5g_rfsim_simple.xml
+[2025-08-07 18:07:49,767]     INFO: ----------------------------------------
+[2025-08-07 18:07:49,767]     INFO: placing all artifacts for this run in /home/richie/oai/cmake_targets/log/container_5g_rfsim_simple.xml.d/
+
+[...]
+
+[2025-08-07 18:07:49,771]     INFO: ----------------------------------------
+[2025-08-07 18:07:49,771]     INFO:  Test ID: 1 (#1)
+[2025-08-07 18:07:49,771]     INFO:  Deploy OAI 5G CoreNetwork
+[2025-08-07 18:07:49,771]     INFO: ----------------------------------------
+```
+
+it will run an end-to-end test, connecting one UE to the gNB, and ping, before
+undeploying. As shown, logs will be under
+`/home/richie/oai/cmake_targets/log/container_5g_rfsim_simple.xml.d/`. The
+python code also produces an HTML report in `ci-scripts/test_results.html`.
+
+# Running with local changes
+
+In order to run the tests as above, with local changes, please [build images
+locally](../docker/README.md).
+
+It is not yet possible to override an existing image with changes made locally
+to a source file and run it directly through the CI framework. However, it is
+possible to override an existing image with local changes, and run the scenario
+manually following the console logs steps provided above. This is described in
+the [5G RFsimulator
+README](yaml_files/5g_rfsimulator/README.md#6-running-with-local-changes).
diff --git a/ci-scripts/xml_files/container_5g_rfsim_simple.xml b/ci-scripts/xml_files/container_5g_rfsim_simple.xml
new file mode 100644
index 0000000000..738ce1a077
--- /dev/null
+++ b/ci-scripts/xml_files/container_5g_rfsim_simple.xml
@@ -0,0 +1,97 @@
+<!--
+
+ Licensed to the OpenAirInterface (OAI) Software Alliance under one or more
+ contributor license agreements.  See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The OpenAirInterface Software Alliance licenses this file to You under
+ the OAI Public License, Version 1.1  (the "License"); you may not use this file
+ except in compliance with the License.
+ You may obtain a copy of the License at
+
+      http://www.openairinterface.org/?page_id=698
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+ For more information about the OpenAirInterface (OAI) Software Alliance:
+      contact@openairinterface.org
+
+-->
+<testCaseList>
+        <htmlTabRef>rfsim-5gnr-tdd</htmlTabRef>
+        <htmlTabName>Monolithic SA TDD gNB</htmlTabName>
+        <htmlTabIcon>wrench</htmlTabIcon>
+        <TestCaseRequestedList>
+ 000001
+ 000002
+ 000003
+ 000008
+ 020001
+ 444444
+ 100001
+        </TestCaseRequestedList>
+        <TestCaseExclusionList></TestCaseExclusionList>
+
+        <testCase id="000001">
+                <class>Deploy_Object</class>
+                <desc>Deploy OAI 5G CoreNetwork</desc>
+                <node>localhost</node>
+                <yaml_path>ci-scripts/yaml_files/5g_rfsimulator</yaml_path>
+                <services>mysql oai-amf oai-smf oai-upf oai-ext-dn</services>
+        </testCase>
+
+        <testCase id="000002">
+                <class>Deploy_Object</class>
+                <desc>Deploy OAI 5G gNB RF sim SA</desc>
+                <node>localhost</node>
+                <yaml_path>ci-scripts/yaml_files/5g_rfsimulator</yaml_path>
+                <services>oai-gnb</services>
+        </testCase>
+
+        <testCase id="000003">
+                <class>Deploy_Object</class>
+                <desc>Deploy OAI 5G NR-UE RF sim SA</desc>
+                <node>localhost</node>
+                <yaml_path>ci-scripts/yaml_files/5g_rfsimulator</yaml_path>
+                <services>oai-nr-ue</services>
+        </testCase>
+
+        <testCase id="000008">
+                <class>Attach_UE</class>
+                <desc>Attach OAI UE (Wait for IP)</desc>
+                <id>rfsim5g_ue</id>
+                <nodes>localhost</nodes>
+        </testCase>
+
+        <testCase id="020001">
+                <class>Ping</class>
+                <desc>Ping ext-dn from NR-UE</desc>
+                <id>rfsim5g_ue</id>
+                <nodes>localhost</nodes>
+                <svr_id>rfsim5g_ext_dn</svr_id>
+                <svr_node>localhost</svr_node>
+                <ping_args>-c 20 -i 0.25</ping_args>
+                <ping_packetloss_threshold>5</ping_packetloss_threshold>
+        </testCase>
+
+        <testCase id="444444">
+                <class>Detach_UE</class>
+                <desc>Detach OAI UE 1</desc>
+                <id>rfsim5g_ue</id>
+                <nodes>localhost</nodes>
+        </testCase>
+
+        <testCase id="100001">
+                <class>Undeploy_Object</class>
+                <always_exec>true</always_exec>
+                <desc>Undeploy all OAI 5G stack</desc>
+                <node>localhost</node>
+                <yaml_path>ci-scripts/yaml_files/5g_rfsimulator</yaml_path>
+                <d_retx_th>1,0,0,0</d_retx_th>
+                <u_retx_th>1,0,0,0</u_retx_th>
+        </testCase>
+
+</testCaseList>
diff --git a/doc/README.md b/doc/README.md
index 40f838750a..226592ac60 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -133,6 +133,8 @@ The other SDRs (AW2S, LimeSDR, ...) have no READMEs.
 - Component tests are under `tests/`. Currently, there is a simple CU-UP
   tester, see the corresponding [README.md](../tests/nr-cuup/README.md).
 - [TESTBenches.md](./TESTBenches.md) lists the CI setup and links to pipelines
+- The CI setup uses a [custom framework](../ci-scripts/README.md) to run
+  end-to-end tests.
 
 # Developer tools