ci: adding docker compose files for testing

.gitignore

@@ -42,21 +42,21 @@ doc/source/images/auto-generated/*
 
 
 # Testing
+./Testing/
+.benchmarks/
+.coverage
+.pytest_cache/
+.tox/
+*,cover
+coverage.xml
 factory/
-Testing/
-UnitTesting/
-TODO
+test-output.xml
 test.sh
-.pytest_cache/
 tests/.coverage
-tests/htmlcov
 tests/cyclic/htmlcov
-.coverage
-*,cover
-.benchmarks/
-test-output.xml
-coverage.xml
-.tox/
+tests/htmlcov
+TODO
+UnitTesting/
 
 \#*
 .\#*

doc/changelog.d/4186.miscellaneous.md

@@ -0,0 +1 @@
+Ci: adding docker compose files for testing

doc/source/getting_started/develop_pymapdl.rst

@@ -147,6 +147,9 @@
    continuous integration/continuous deployment (CI/CD) pipelines to catch issues early
    and ensure reliable deployments. For more information, see `Unit testing`_.
 
+   .. note:: No pull request is accepted if the amount of test coverage is not sufficient.
+      If you are adding new code, ensure that it is covered by existing or new unit tests.
+
 #. **Respect code style and standards**: Follow code style
    guidelines and adhere to coding standards specific to your language or
    framework.
@@ -228,38 +231,6 @@
 integration test is that the latter tests several units of the code to ensure
 that they all work together.
 
-To run all the unit tests use the following command:
-
-.. code:: console
-
-   (.venv) mapdl@machine:~/pymapdl$ pytest
-
-If you are running on a **Linux machine without display**, you must install ``xvfb`` OS
-library and run the preceding command with the ``xvfb-run`` command as prefix. 
-
-.. code:: console
-
-   (.venv) mapdl@machine:~/pymapdl$ xvfb-run pytest
-
-In case you want to run only a certain subset of tests, you can use the ``-k`` argument
-to filter the tests using booleans:
-
-.. code:: console
-
-   (.venv) mapdl@machine:~/pymapdl$ pytest -k "test_nlist_to_array or test_string_with_literal"
-   ==================================================== test session starts ====================================================
-   platform darwin -- Python 3.10.13, pytest-7.4.3, pluggy-1.3.0
-   rootdir: /Users/german.ayuso/pymapdl
-   configfile: pyproject.toml
-   testpaths: tests
-   plugins: timeout-2.2.0, cov-4.1.0, sphinx-0.5.0, rerunfailures-13.0, anyio-4.1.0, pytest_pyvista-0.1.9
-   collected 1468 items / 1466 deselected / 4 skipped / 2 selected
-
-   tests/test_commands.py ..                                                                                             [100%]
-
-   =============================================== PyMAPDL Pytest short summary ================================================
-   ======================================= 2 passed, 4 skipped, 1466 deselected in 2.27s =======================================
-
 
 Creation of a unit test
 -----------------------
@@ -297,34 +268,85 @@
 
 Passing the ``cleared`` fixture is also useful since it clears up the MAPDL database
 and configuration before performing the test.
-If you do not have MAPDL installed locally but still want to run the
-unit testing, you must set up the following environment variables.
 
-.. tab-set::
+Running PyMAPDL tests
+---------------------
+
+To run all the unit tests use the following command:
+
+.. code:: console
+
+   (.venv) mapdl@machine:~/pymapdl$ pytest
+
+If you just want to run a specific test file, you can provide the path to the file:
+
+.. code:: console
+
+   (.venv) mapdl@machine:~/pymapdl$ pytest tests/test_commands.py
+
+In case you want to run only a certain subset of tests, you can use the ``-k`` argument
+to filter the tests using booleans:
+
+.. code:: console
 
-    .. tab-item:: Windows
-        :sync: key1
+   (.venv) mapdl@machine:~/pymapdl$ pytest -k "test_nlist_to_array or test_string_with_literal"
+   ======================================= test session starts ====================================================
+   platform darwin -- Python 3.10.13, pytest-7.4.3, pluggy-1.3.0
+   rootdir: /Users/german.ayuso/pymapdl
+   configfile: pyproject.toml
+   testpaths: tests
+   plugins: timeout-2.2.0, cov-4.1.0, sphinx-0.5.0, rerunfailures-13.0, anyio-4.1.0, pytest_pyvista-0.1.9
+   collected 1468 items / 1466 deselected / 4 skipped / 2 selected
 
-        .. code:: pwsh-session
+   tests/test_commands.py ..                                                                                             [100%]
 
-            SET PYMAPDL_START_INSTANCE=False
-            SET PYMAPDL_PORT=<MAPDL Port> (default 50052)
-            SET PYMAPDL_IP=<MAPDL IP> (default 127.0.0.1)
+   ================================= PyMAPDL Pytest short summary ================================================
+   ========================= 2 passed, 4 skipped, 1466 deselected in 2.27s =======================================
 
-    .. tab-item:: Linux
-        :sync: key1
-
-        .. code:: console
+If you are running on a **Linux machine without display** (for example running from
+a container), you must install ``xvfb`` OS library and run the preceding command with the ``xvfb-run`` command as prefix.
 
-            export PYMAPDL_START_INSTANCE=False
-            export PYMAPDL_PORT=<MAPDL Port> (default 50052)
-            export PYMAPDL_IP=<MAPDL IP> (default 127.0.0.1)
+.. code:: console
 
+   (.venv) mapdl@machine:~/pymapdl$ xvfb-run pytest
 
-These environment variables tell PyMAPDL to attempt to connect to the existing
-MAPDL service by default when the ``launch_mapdl`` function is used.
 
-Additionally, you can use the :envvar:`PYMAPDL_MAPDL_EXEC` and :envvar:`PYMAPDL_MAPDL_VERSION`
+Configuring the test suite
+--------------------------
+
+PyMAPDL can operate in multiple situations, or configurations.
+To test these different configurations, you can use the `pytest` framework with specific environment variables.
+
+The list of environment variables that can be set includes:
+
++-----------------------------------+------------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Environment variable              | Values           | Default         | Usage                                                                                                                                                                                                                                                         |
++===================================+==================+=================+===============================================================================================================================================================================================================================================================+
+| :envvar:`ON_CI`                   | `True`/`False`   | `False`         |  Tell Pytest it is running on GitHub Actions                                                                                                                                                                                                                  |
++-----------------------------------+------------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| :envvar:`ON_LOCAL`                | `True`/`False`   | Detected        |  Tell Pytest that PyMAPDL is running on local, and the test should match that.  The default is to detect whether MAPDL is installed or not. If the environment variable :envvar:`PYMAPDL_START_INSTANCE` is set, then :envvar:`ON_LOCAL` is `False`.          |
++-----------------------------------+------------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| :envvar:`ON_UBUNTU`               | `True`/`False`   | Detected        |  Tell Pytest that PyMAPDL is running on Ubuntu, and the test should match that.                                                                                                                                                                               |
++-----------------------------------+------------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| :envvar:`ON_STUDENT`              | `True`/`False`   | `False`         |  Tell Pytest that PyMAPDL is running on a student environment, and the test should match that.                                                                                                                                                                |
++-----------------------------------+------------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| :envvar:`TESTING_MINIMAL`         | `True`/`False`   | `False`         |  Tell Pytest that PyMAPDL is installed with the minimal requirements, hence it won't run tests that requires libraries like Pyvista, DPF, etc.                                                                                                                |
++-----------------------------------+------------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| :envvar:`PYMAPDL_DEBUG_TESTING`   | `True`/`False`   | `False`         |  Tell PyMAPDL to enable debug while testing. This means that the APDL commands are recorded to the file `pymapdl.apdl` and the debug calls are logged into the file `pymapdl.log`.                                                                            |
++-----------------------------------+------------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| :envvar:`HAS_GRPC`                | `True`/`False`   | Detected        |  Tell PyMAPDL that the gRPC interface is available for testing. If `TESTING_MINIMAL` is `True`, then this is `True` by default.                                                                                                                               |
++-----------------------------------+------------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| :envvar:`HAS_DPF`                 | `True`/`False`   | `False`         |  Tell Pytest that DPF should be tested.                                                                                                                                                                                                                       |
++-----------------------------------+------------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| :envvar:`DISTRIBUTED_MODE`        | `smp`/`dmp`      | `smp`           |  Tell Pytest that MAPDL is running a given distributed mode.                                                                                                                                                                                                  |
++-----------------------------------+------------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| :envvar:`SUPPORT_PLOTTING`        | `True`/`False`   | Detected        |  Tell Pytest that the machine supports plotting (i.e. it has a display).                                                                                                                                                                                      |
++-----------------------------------+------------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| :envvar:`TEST_DPF_BACKEND`        | `Yes`/`No`       | `NO`            |  Tell Pytest that the module `Result` with DPF backend should be tested.                                                                                                                                                                                      |
++-----------------------------------+------------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+Additionally, you can use any `PyMAPDL environment variables <ref_environment_variables_>`_ 
+like the :envvar:`PYMAPDL_MAPDL_EXEC` and :envvar:`PYMAPDL_MAPDL_VERSION`
 environment variables to specify the MAPDL executable path and the version to launch (if
 multiple versions of MAPDL are installed).
 

doc/source/getting_started/docker.rst

@@ -261,7 +261,7 @@ you can use the following command to launch MAPDL:
 Connect to the MAPDL container from Python
 ==========================================
 
-You can connect to an MAPDL instance as indicated in :ref:`connect_grpc_madpl_session`.
+You can connect to an MAPDL instance as indicated in :ref:`connect_grpc_mapdl_session`.
 You do not need to specify an IP address because Docker maps the ports to the local host.
 
 

doc/source/getting_started/launcher.rst

@@ -48,7 +48,7 @@ Connect PyMAPDL to a local MAPDL instance
 Connect to a local MAPDL instance requires two steps: launching a
 local MAPDL session and connect to it.
 
-.. _launch_grpc_madpl_session:
+.. _launch_grpc_mapdl_session:
 
 Launch a local gRPC MAPDL session
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -115,7 +115,7 @@ From version v0.68, you can use a command line interface to launch, stop, and li
 local MAPDL instances.
 For more information, see :ref:`ref_cli`.
 
-.. _connect_grpc_madpl_session:
+.. _connect_grpc_mapdl_session:
 
 Connect to the local MAPDL instance
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -143,7 +143,7 @@ Just make sure that you specify the mapped port instead of the internal MAPDL po
 For more information, see :ref:`pymapdl_docker`.
 
 
-.. _connect_grpc_remote_madpl_session:
+.. _connect_grpc_remote_mapdl_session:
 
 Connect PyMAPDL to a remote MAPDL instance
 ------------------------------------------

doc/source/getting_started/macos.rst

@@ -21,7 +21,7 @@ MAPDL is not compatible with a MacOS.
 There are two options:
 
 * **Connect to a remote instance**: You can connect to a remote instance running
-  on a Windows or Linux machine as indicated in :ref:`connect_grpc_madpl_session`.
+  on a Windows or Linux machine as indicated in :ref:`connect_grpc_mapdl_session`.
 
 * **Launch MAPDL locally using Docker**: You can run MAPDL on a MacOS machine as
   indicated in :ref:`launch_mapdl_on_macos`.
@@ -64,6 +64,6 @@ as shown in this code example:
 Connect to an MAPDL container
 =============================
 
-You can connect to an MAPDL instance as indicated in :ref:`connect_grpc_madpl_session`.
+You can connect to an MAPDL instance as indicated in :ref:`connect_grpc_mapdl_session`.
 
 

doc/source/getting_started/make_container.rst

@@ -1,3 +1,3 @@
 .. _ref_make_container:
 
-.. include:: ../../../docker/make_container.rst
+.. include:: ../../../docker/MAPDL/make_container.rst

doc/source/user_guide/troubleshoot.rst

@@ -273,7 +273,7 @@
             FlexNet Licensing error:-5,357
 
 
 If there are not enough licenses available, you might see an error similar to the above one. 
 In these cases you should contact your Ansys license administrator at your organization.
 
 If you are responsible for maintaining Ansys licensing or have a personal installation of Ansys, see the online
@@ -803,7 +803,7 @@
 
 When connecting to an instance of MAPDL using gRPC (default), there are some cases
 where the MAPDL server might exit unexpectedly. There
-are several ways to improve MADPL performance and stability:
+are several ways to improve MAPDL performance and stability:
 
 Use ``mute`` to improve stability
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docker/make_container.rst → docker/MAPDL/make_container.rst

@@ -24,8 +24,8 @@ Requirements
 
 * The following provided files:
 
-  * `Dockerfile <https://github.com/ansys/pymapdl/tree/main/docker/Dockerfile>`_
-  * `.dockerignore <https://github.com/ansys/pymapdl/tree/main/docker/.dockerignore>`_
+  * `Dockerfile <https://github.com/ansys/pymapdl/tree/main/docker/MAPDL/Dockerfile>`_
+  * `.dockerignore <https://github.com/ansys/pymapdl/tree/main/docker/MAPDL/.dockerignore>`_
 
 
 Procedure
@@ -100,10 +100,10 @@ Please notice that:
 * ``path_to_mapdl_installation`` is the path to where you have locally installed ANSYS MAPDL.
 
 Not all the installation files are copied, in fact, the files ignored during the copying
-are detailed in the file `.dockerignore <https://github.com/ansys/pymapdl/tree/main/docker/.dockerignore>`_.
+are detailed in the file `.dockerignore <https://github.com/ansys/pymapdl/tree/main/docker/MAPDL/.dockerignore>`_.
 
 The Docker container configuration needed to build the container is detailed in the
-`Dockerfile <https://github.com/ansys/pymapdl/tree/main/docker/Dockerfile>`_.
+`Dockerfile <https://github.com/ansys/pymapdl/tree/main/docker/MAPDL/Dockerfile>`_.
 
 
 Summary