Skip to content

ci: adding docker compose files for testing #4186

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 19 commits into
base: main
Choose a base branch
from
Open

ci: adding docker compose files for testing #4186

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
0af3a19
refactor: Update MAPDL Docker setup and documentation. Moved MAPDL do…
germa89 Aug 8, 2025
505625c
feat: Add Docker setup for PyMAPDL testing environment with Dockerfil…
germa89 Aug 11, 2025
a028637
feat: Enhance Docker setup and testing scripts for PyMAPDL with impro…
germa89 Aug 14, 2025
e31b2ed
refactor: Update docker-compose.yml to correct service name and remov…
germa89 Aug 14, 2025
dcac765
refactor: Update docker-compose.yml to standardize service name casing
germa89 Aug 14, 2025
8820345
refactor: Update Dockerfile and docker-compose.yml to improve configu…
germa89 Aug 14, 2025
4db251a
refactor: Update Dockerfile and docker-compose.yml for improved confi…
germa89 Aug 18, 2025
f11d019
feat: Add Dockerfile, docker-compose.yml, mylocal.ip, and start.sh fo…
germa89 Aug 19, 2025
1f1829b
chore: adding changelog file 4186.miscellaneous.md [dependabot-skip]
pyansys-ci-bot Aug 19, 2025
77afe05
Apply suggestions from code review
germa89 Aug 20, 2025
d1ceacf
fix: Correct spelling of MAPDL in documentation and comments
germa89 Aug 20, 2025
96dfea8
refactor: Clean up .gitignore by standardizing testing entries and re…
germa89 Aug 20, 2025
f81084a
docs: add testing env vars table.
germa89 Aug 20, 2025
b1d0667
Merge branch 'ci/adding-pymapdl-docker-image' of https://github.com/a…
germa89 Aug 20, 2025
af442f0
fix: Simplify comment in has_grpc function to clarify gRPC assumption
germa89 Aug 20, 2025
b23c26e
fix: Correct indentation in docker-compose.yml for default service
germa89 Aug 20, 2025
00f1d81
fix: Update docker-compose.yml to add missing comment for volume requ…
germa89 Aug 20, 2025
8a0a5d1
fix: Update environment variable vocabulary to include DMP and SMP
germa89 Aug 21, 2025
d3f1fc6
fix: Clarify message regarding insufficient licenses for MAPDL startup
germa89 Aug 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 11 additions & 11 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/

\#*
.\#*
Expand Down
1 change: 1 addition & 0 deletions doc/changelog.d/4186.miscellaneous.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Ci: adding docker compose files for testing
124 changes: 73 additions & 51 deletions doc/source/getting_started/develop_pymapdl.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
-----------------------
Expand Down Expand Up @@ -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). |

Check failure on line 343 in doc/source/getting_started/develop_pymapdl.rst

View workflow job for this annotation

GitHub Actions / Documentation style doc 

[vale] reported by reviewdog 🐶
[Google.Latin] Use 'that is' instead of 'i.e.'.

Raw Output:
{"message": "[Google.Latin] Use 'that is' instead of 'i.e.'.", "location": {"path": "doc/source/getting_started/develop_pymapdl.rst", "range": {"start": {"line": 343, "column": 125}}}, "severity": "ERROR"}
+-----------------------------------+------------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :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).

Expand Down
2 changes: 1 addition & 1 deletion doc/source/getting_started/docker.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.


Expand Down
6 changes: 3 additions & 3 deletions doc/source/getting_started/launcher.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -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
------------------------------------------
Expand Down
4 changes: 2 additions & 2 deletions doc/source/getting_started/macos.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand Down Expand Up @@ -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`.


2 changes: 1 addition & 1 deletion doc/source/getting_started/make_container.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
.. _ref_make_container:

.. include:: ../../../docker/make_container.rst
.. include:: ../../../docker/MAPDL/make_container.rst
4 changes: 2 additions & 2 deletions doc/source/user_guide/troubleshoot.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -273,7 +273,7 @@ In such cases, if you try to start MAPDL from the command line you might see an
FlexNet Licensing error:-5,357


If there are not enough licenses available, you might see an error similar to the above one.
This means that there are not enough licenses available to start MAPDL.
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
Expand Down Expand Up @@ -803,7 +803,7 @@ Recommendations

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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down
2 changes: 2 additions & 0 deletions doc/styles/config/vocabularies/ANSYS/accept.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,7 @@ devcontainer
DevContainer
Dimitris
discretisation
DMP
dof
ect
eigenfrequency
Expand Down Expand Up @@ -162,6 +163,7 @@ singl
Slurm
SLURM
smal
SMP
sord
spotweld
squeue
Expand Down
0 docker/.dockerignore → docker/MAPDL/.dockerignore
View file
Open in desktop
File renamed without changes.
0 docker/Dockerfile → docker/MAPDL/Dockerfile
View file
Open in desktop
File renamed without changes.
0 docker/docker-compose.yml → docker/MAPDL/docker-compose.yml
View file
Open in desktop
File renamed without changes.
8 changes: 4 additions & 4 deletions docker/make_container.rst → docker/MAPDL/make_container.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
Loading
Loading