docs: Add documentation to start the integration tests.

Author: Robin-Van-de-Merghel

docs/source/DeveloperGuide/CodeTesting/index.rst

@@ -309,10 +309,8 @@ Running the above might take a while. Supposing you are interested in running on
     ./integration_tests.py prepare-environment [FLAGS]
     ./integration_tests.py install-server
 
-which (in some minutes) will give you a fully dockerized server setup
-(`docker container ls` will list the created container, and you can see what's going on inside with the standard `docker exec -it server /bin/bash`.
-Now, suppose that you want to run `WorkloadManagementSystem/Test_JobDB.py`,
-the first thing to do is that you should first login in the docker container, by doing:
+which (in some minutes) will give you a fully dockerized server setup. `docker container ls` will list the created container, and you can see what's going on inside with the standard `docker exec -it server /bin/bash`.
+Now, suppose that you want to run `WorkloadManagementSystem/Test_JobDB.py`, the first thing to do is that you should first login in the docker container, by doing:
 
 .. code-block:: bash
 
@@ -326,7 +324,7 @@ Now you can run the test with:
 
     pytest --no-check-dirac-environment LocalRepo/ALTERNATIVE_MODULES/DIRAC/tests/Integration/WorkloadManagementSystem/Test_JobDB.py
 
-You can find the logs of the services in `/home/dirac/ServerInstallDIR/diracos/runit/`
+You can find the logs of the services in `/home/dirac/ServerInstallDIR/diracos/runit/`.
 
 You can also login in client and mysql with:
 
@@ -335,7 +333,49 @@ You can also login in client and mysql with:
     ./integration_tests.py exec-client
     ./integration_tests.py exec-mysql
 
+To restart a service, you can go into the server docker, and run `runsvctrl`:
 
+.. code-block:: bash
+
+    ./integration_tests.py exec-server
+    ...
+    runsvctrl t /home/dirac/ServerInstallDIR/diracos/runit/WorkloadManagement/JobMonitor/
+
+And you can also restart all services (it can take some time):
+
+.. code-block:: bash
+
+    ./integration_tests.py exec-server
+    ...
+    runsvctrl t /home/dirac/ServerInstallDIR/diracos/runit/*/*
+
+
+You can also test DiracX in integration tests. To do that, you have to provide in the `prepare-environment` command the following flag: `TEST_DIRACX=Yes`. It will run DiracX alongside DIRAC, and use the available and activated legacy adapted services.
+
+To deactivate a service from being used with DiracX, you can set the `diracxClient` field to `None`:
+
+.. code-block:: python
+
+    class MyOldClient(Client):
+      def __init__(self, **kwargs):
+          super().__init__(**kwargs)
+          self.setServer("...")
+
+      # Set to NULL to avoid using it in ClientSelector
+      diracxClient = None
+
+By setting `TEST_DIRACX=Yes` only, it will take the last version of DiracX by default. If you want to provide your own, you have to build your DiracX project, and provide the `dist` folder path when calling `prepare-client`. This path has to be absolute.
+
+.. code-block:: bash
+
+    ./integration-tests.py prepare-client TEST_DIRACX=Yes --diracx-dist-dir my-dist-folder/
+
+It will then mount your dist folder into DIRAC and DiracX (in `/diracx_sources`) to install the right dependencies.
+
+For MacOS, there are two bugs that can be fixed.
+
+- The first one is about `docker compose` not being recognized. To fix that, you can set in your environment variables `DOCKER_COMPOSE_CMD="docker-compose"`.
+- The second one, is for macs with M1 (or more recent ones) chips which are not supported by the `opensearch` docker image. By setting the `ES_PLATFORM` flag to `linux/arm64` you will be able to start `opensearch` without issue.
 
 Validation and System tests
 ---------------------------

integration_tests.py

@@ -25,6 +25,8 @@
 DEFAULT_HOST_OS = "el9"
 DEFAULT_MYSQL_VER = "mysql:8.4.4"
 DEFAULT_ES_VER = "opensearchproject/opensearch:2.18.0"
+# In MacOSX with Arm (MX), there's an issue with opensearch
+# You *must* set the ES_PLATFORM flag to `linux/arm64` to make it work.
 DEFAULT_ES_PLATFORM = "linux/amd64"
 DEFAULT_IAM_VER = "indigoiam/iam-login-service:v1.10.2"
 FEATURE_VARIABLES = {
@@ -37,6 +39,7 @@
     "INSTALLATION_BRANCH": "",
     "DEBUG": "Yes",
 }
+# If TEST_DIRACX is set to yes, all variables in DIRACX_OPTIONS will also be set to "Yes"
 DIRACX_OPTIONS = ()
 DEFAULT_MODULES = {"DIRAC": Path(__file__).parent.absolute()}
 
@@ -72,6 +75,8 @@
 }
 LOG_PATTERN = re.compile(r"^[\d\-]{10} [\d:]{8} UTC [^\s]+ ([A-Z]+):")
 
+# In niche cases where we use MacOSX with Orbstack, some commands may not work with docker compose
+# If you're in that case, set in your environment `export DOCKER_COMPOSE_CMD="docker-compose"`
 DOCKER_COMPOSE_CMD = shlex.split(os.environ.get("DOCKER_COMPOSE_CMD", "docker compose"))
 
 
@@ -143,6 +148,18 @@ def list_commands(self, ctx):
 After restarting your terminal you command completion is available using:
 
   typer ./integration_tests.py run ...
+
+## DiracX
+
+If you want to activate DiracX, you have to set the flag TEST_DIRACX to "Yes".
+It will search for legacy adapted services (services with a future client activated)
+and do the necessary to make DIRAC work alongside DiracX.
+
+To deactivate a legacy adapted service (to pass CI for example), you have to set in the old
+client the `diracxClient` field to "None". Else, set it to the right future client instance.
+
+> Note that you can provide a DiracX project (repository, branch) by building it and providing
+the dist folder to the prepare-environment command.
 """,
 )