test.yml

# Run the complete test suite incl. many external command line dependencies (like Openbabel)
# as well as the pymatgen.ext package. Coverage used to be computed based on this workflow.
name: test

on:
  push:
    paths:
      [
        "src/**/*.*",
        "tests/**/*.*",
        ".github/workflows/*",
        "pyproject.toml",
        "setup.py",
      ]
  pull_request:
    paths:
      [
        "src/**/*.*",
        "tests/**/*.*",
        ".github/workflows/*",
        "pyproject.toml",
        "setup.py",
      ]
  workflow_dispatch:
  workflow_call: # make this workflow reusable by release.yml

permissions:
  contents: read
  id-token: write  # required for the codecov OIDC upload below

jobs:
  test:
    # Prevent this action from running on forks
    if: github.repository == 'materialsproject/pymatgen-core'
    defaults:
      run:
        shell: bash -leo pipefail {0} # Enable mamba env activation by reading bash profile
    strategy:
      fail-fast: false
      matrix:
        # Maximize CI coverage of different platforms and Python versions while minimizing the
        # total number of jobs. We run all pytest splits with the oldest supported Python
        # version on windows (most likely to surface errors) and with
        # newest version on Ubuntu (to get complete coverage).
        config:
          - os: windows-latest
            python: "3.13"  # Test lowest supported Python version
            resolution: lowest-direct
          - os: macos-latest
            python: "3.13"
            resolution: lowest-direct
            extras: optional
          - os: ubuntu-latest
            python: "3.11"  # Test highest supported Python version
            resolution: lowest-direct
          - os: ubuntu-latest
            python: "3.14"  # Test highest supported Python version
            resolution: highest
            extras: optional

    runs-on: ${{ matrix.config.os }}
    env:
      OPT_BIN_DIR: ${{ github.workspace }}/opt/bin # for optional Ubuntu dependencies
    steps:
      - name: Check out repo
        uses: actions/checkout@v6
        with:
          submodules: recursive

      # setup-micromamba is broken on Windows runners since ~2026-05-14
      # (micromamba shell init fails with STATUS_DLL_NOT_FOUND, exit 3221225781).
      # Upstream: https://github.com/mamba-org/setup-micromamba/issues/306
      # The Windows job has no conda-only dependencies, so plain setup-python
      # is sufficient. Revert to micromamba on Windows once #306 is fixed.
      - name: Set up Python (Windows)
        if: matrix.config.os == 'windows-latest'
        uses: actions/setup-python@v6
        with:
          python-version: ${{ matrix.config.python }}

      - name: Create mamba environment
        if: matrix.config.os != 'windows-latest'
        uses: mamba-org/setup-micromamba@v3
        with:
          environment-name: pmg
          cache-environment: true
          create-args: >-
            python=${{ matrix.config.python }}

      - name: Install ubuntu-only conda dependencies
        if: matrix.config.os == 'ubuntu-latest'
        run: |
          micromamba install -n pmg -c conda-forge bader enumlib \
            packmol pygraphviz tblite --yes
            # openff-toolkit # TODO: doesn't support Python 3.13 yet

      - name: Install uv
        uses: astral-sh/setup-uv@v8.1.0

      # On Ubuntu/macOS the micromamba ``pmg`` env serves as the install
      # target for ``uv pip install``. Windows has no micromamba env (see
      # above), so create a uv venv explicitly so subsequent uv/pytest
      # steps have a target on PATH.
      - name: Create uv venv (Windows)
        if: matrix.config.os == 'windows-latest'
        run: |
          uv venv .venv --python ${{ matrix.config.python }}
          echo "VIRTUAL_ENV=$PWD/.venv" >> $GITHUB_ENV
          echo "$PWD/.venv/Scripts" >> $GITHUB_PATH

      - name: Install pymatgen and dependencies via uv
        run: |
          # Install from wheels to test the content
          uv build --wheel --no-build-logs
          WHEEL_FILE=$(ls dist/pymatgen*.whl)
          uv pip install $WHEEL_FILE[${{matrix.config.extras}}] --group test \
            --resolution=${{matrix.config.resolution}}

      - name: Restore cache for optional Ubuntu/MacOS dependencies
        if: matrix.config.os == 'ubuntu-latest' || matrix.config.os == 'macos-latest'
        id: optbin-cache
        uses: actions/cache@v5
        with:
          path: ${{ env.OPT_BIN_DIR }}
          key: opt-bin-${{ runner.os }}-${{ hashFiles('.github/workflows/_install_opt_unit_deps.sh') }}

      - name: Build optional Ubuntu/MacOS dependencies (when cache misses)
        if: (matrix.config.os == 'ubuntu-latest' || matrix.config.os == 'macos-latest') && steps.optbin-cache.outputs.cache-hit != 'true'
        run: bash .github/workflows/_install_opt_unit_deps.sh "$OPT_BIN_DIR"

      - name: pytest
        env:
          MPLBACKEND: Agg # non-interactive backend for matplotlib
          PMG_MAPI_KEY: ${{ secrets.PMG_MAPI_KEY }}
          PMG_TEST_FILES_DIR: "${{ github.workspace }}/test-files"
          PYTHONWARNDEFAULTENCODING: "true" # PEP 597: Enable optional EncodingWarning
        run: |
          pytest --cov=pymatgen --cov-report=xml tests --color=yes
      - name: Codecov
        # Upload from the ubuntu shard that installs `extras: optional` so
        # codecov reflects the full test surface. The python 3.11 shard runs
        # without extras and was previously uploading misleadingly low numbers
        # for any file gated on ase/seekpath/phonopy/etc.
        # Uses GitHub OIDC (no shared secret); requires "Tokenless Upload"
        # to be enabled at https://app.codecov.io/gh/materialsproject/pymatgen-core
        if: github.ref == 'refs/heads/main' && matrix.config.os == 'ubuntu-latest' && matrix.config.extras == 'optional'
        uses: codecov/codecov-action@v6
        with:
          use_oidc: true