Tests workflow (TorchSim/torch-sim)

The Tests workflow from TorchSim/torch-sim, explained and optimized by Latchkey.

CI health: C - fair

Point runs-on at Latchkey and get caching, job timeouts, SHA-pinned actions, self-healing for flaky steps, and up to 58% lower cost, applied automatically.

Grade your own workflow free or run it on Latchkey →

Source: TorchSim/torch-sim.github/workflows/test.ymlLicense MITView source

What it does

This is the Tests workflow from the TorchSim/torch-sim repository, a real project running GitHub Actions. It is shown here with attribution under its MIT license.

Below, Latchkey shows a faster, safer version produced by its optimization engine.

The workflow

workflow (.yml)

name: Tests

on:
  push:
    branches: [main]
  pull_request:
  workflow_dispatch:
  workflow_call:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  test-core:
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-14]
        version:
          - { python: '3.12', resolution: highest }
          - { python: '3.12', resolution: lowest-direct }
          - { python: '3.14', resolution: highest }
          - { python: '3.14', resolution: lowest-direct }
    runs-on: ${{ matrix.os }}

    steps:
      - name: Check out repo
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.version.python }}

      - name: Set up uv
        uses: astral-sh/setup-uv@v6

      - name: Install torch_sim
        run: |
          uv pip install "torch>2" --index-url https://download.pytorch.org/whl/cpu --system
          uv pip install -e ".[test]" --resolution=${{ matrix.version.resolution }} --system

      - name: Run core tests
        run: |
          pytest --cov=torch_sim --cov-report=xml

      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@v5
        with:
          token: ${{ secrets.CODECOV_TOKEN }}
          slug: torchsim/torch-sim

  test-model:
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-14]
        version:
          - { python: '3.12', resolution: lowest-direct }
          - { python: '3.14', resolution: highest }
        model:
          - { name: fairchem, test_path: "tests/models/test_fairchem.py" }
          - { name: mace, test_path: "tests/models/test_mace.py" }
          - { name: mace, test_path: "tests/test_elastic.py" }
          - { name: mace, test_path: "tests/test_optimizers_vs_ase.py" }
          - { name: mattersim, test_path: "tests/models/test_mattersim.py" }
          - { name: metatomic, test_path: "tests/models/test_metatomic.py" }
          - { name: nequip, test_path: "tests/models/test_nequip_framework.py" }
          - { name: nequix, test_path: "tests/models/test_nequix.py" }
          - { name: orb, test_path: "tests/models/test_orb.py" }
          - { name: sevenn, test_path: "tests/models/test_sevennet.py" }
        exclude:
          - version: { python: '3.14', resolution: highest }
            model: { name: orb, test_path: 'tests/models/test_orb.py' }
          - version: { python: '3.14', resolution: highest }
            model: { name: fairchem, test_path: 'tests/models/test_fairchem.py'}
          - version: { python: '3.14', resolution: highest }
            model: { name: nequip, test_path: 'tests/models/test_nequip_framework.py'}
    runs-on: ${{ matrix.os }}

    steps:
      - name: Check out repo
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.version.python }}

      - name: Install HDF5 on macOS
        if: runner.os == 'macOS'
        run: brew install hdf5

      - name: Set up uv
        uses: astral-sh/setup-uv@v6

      - name: Install torch_sim with model dependencies
        run: |
          # setuptools <82 provides pkg_resources needed by mattersim and fairchem (via torchtnt).
          # setuptools 82+ removed pkg_resources. Remove pin once those packages migrate.
          uv pip install -e ".[test,${{ matrix.model.name }}]" "setuptools>=70,<82" --resolution=${{ matrix.version.resolution }} --system

      - name: Run ${{ matrix.model.test_path }} tests
        if: ${{ !contains(matrix.model.name, 'fairchem') || github.event.pull_request.head.repo.fork == false }}
        env:
          HF_TOKEN: ${{ secrets.HUGGING_FACE_TOKEN }}
        run: |
          if [[ "${{ matrix.model.name }}" == *"fairchem"* ]]; then
            uv pip install huggingface_hub --system
          fi
          pytest -vv -ra -rs --cov=torch_sim --cov-report=xml ${{ matrix.model.test_path }}

      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@v5
        with:
          token: ${{ secrets.CODECOV_TOKEN }}
          slug: torchsim/torch-sim

  find-examples:
    runs-on: ubuntu-latest
    outputs:
      examples: ${{ steps.set-matrix.outputs.examples }}
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Find example scripts
        id: set-matrix
        run: |
          EXAMPLES=$(find examples -name "*.py" -not -path "examples/benchmarking/*" | jq -R -s -c 'split("\n")[:-1]')
          echo "examples=$EXAMPLES" >> $GITHUB_OUTPUT

  test-examples:
    needs: find-examples
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        example: ${{fromJson(needs.find-examples.outputs.examples)}}
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Set up uv
        uses: astral-sh/setup-uv@v6

      - name: Run example
        if: ${{ !contains(matrix.example, 'fairchem') || github.event.pull_request.head.repo.fork == false }}
        env:
          HF_TOKEN: ${{ secrets.HUGGING_FACE_TOKEN }}
        run: |
          if [[ "${{ matrix.example }}" == *"fairchem"* ]]; then
            uv pip install huggingface_hub --system
          fi
          uv run --with-editable . ${{ matrix.example }}

  all-required-pass:
    if: always()
    needs: [test-core, test-examples]
    runs-on: ubuntu-latest
    steps:
      - name: Check all required jobs passed
        run: |
          if [[ "${{ needs.test-core.result }}" != "success" ]]; then
            echo "test-core failed or was cancelled"
            exit 1
          fi
          if [[ "${{ needs.test-examples.result }}" != "success" ]]; then
            echo "test-examples failed or was cancelled"
            exit 1
          fi
          echo "All required jobs passed"

The same workflow, on Latchkey

Estimated ~20% faster on cache hits, plus fewer wasted runs and a safer supply chain. Added and changed lines are highlighted.

name: Tests
 
on:
  push:
    branches: [main]
  pull_request:
  workflow_dispatch:
  workflow_call:
 
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true
 
jobs:
  test-core:
    timeout-minutes: 30
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-14]
        version:
          - { python: '3.12', resolution: highest }
          - { python: '3.12', resolution: lowest-direct }
          - { python: '3.14', resolution: highest }
          - { python: '3.14', resolution: lowest-direct }
    runs-on: ${{ matrix.os }}
 
    steps:
      - name: Check out repo
        uses: actions/checkout@v4
 
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          cache: 'pip'
          python-version: ${{ matrix.version.python }}
 
      - name: Set up uv
        uses: astral-sh/setup-uv@v6
 
      - name: Install torch_sim
        run: |
          uv pip install "torch>2" --index-url https://download.pytorch.org/whl/cpu --system
          uv pip install -e ".[test]" --resolution=${{ matrix.version.resolution }} --system
 
      - name: Run core tests
        run: |
          pytest --cov=torch_sim --cov-report=xml
 
      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@v5
        with:
          token: ${{ secrets.CODECOV_TOKEN }}
          slug: torchsim/torch-sim
 
  test-model:
    timeout-minutes: 30
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-14]
        version:
          - { python: '3.12', resolution: lowest-direct }
          - { python: '3.14', resolution: highest }
        model:
          - { name: fairchem, test_path: "tests/models/test_fairchem.py" }
          - { name: mace, test_path: "tests/models/test_mace.py" }
          - { name: mace, test_path: "tests/test_elastic.py" }
          - { name: mace, test_path: "tests/test_optimizers_vs_ase.py" }
          - { name: mattersim, test_path: "tests/models/test_mattersim.py" }
          - { name: metatomic, test_path: "tests/models/test_metatomic.py" }
          - { name: nequip, test_path: "tests/models/test_nequip_framework.py" }
          - { name: nequix, test_path: "tests/models/test_nequix.py" }
          - { name: orb, test_path: "tests/models/test_orb.py" }
          - { name: sevenn, test_path: "tests/models/test_sevennet.py" }
        exclude:
          - version: { python: '3.14', resolution: highest }
            model: { name: orb, test_path: 'tests/models/test_orb.py' }
          - version: { python: '3.14', resolution: highest }
            model: { name: fairchem, test_path: 'tests/models/test_fairchem.py'}
          - version: { python: '3.14', resolution: highest }
            model: { name: nequip, test_path: 'tests/models/test_nequip_framework.py'}
    runs-on: ${{ matrix.os }}
 
    steps:
      - name: Check out repo
        uses: actions/checkout@v4
 
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          cache: 'pip'
          python-version: ${{ matrix.version.python }}
 
      - name: Install HDF5 on macOS
        if: runner.os == 'macOS'
        run: brew install hdf5
 
      - name: Set up uv
        uses: astral-sh/setup-uv@v6
 
      - name: Install torch_sim with model dependencies
        run: |
          # setuptools <82 provides pkg_resources needed by mattersim and fairchem (via torchtnt).
          # setuptools 82+ removed pkg_resources. Remove pin once those packages migrate.
          uv pip install -e ".[test,${{ matrix.model.name }}]" "setuptools>=70,<82" --resolution=${{ matrix.version.resolution }} --system
 
      - name: Run ${{ matrix.model.test_path }} tests
        if: ${{ !contains(matrix.model.name, 'fairchem') || github.event.pull_request.head.repo.fork == false }}
        env:
          HF_TOKEN: ${{ secrets.HUGGING_FACE_TOKEN }}
        run: |
          if [[ "${{ matrix.model.name }}" == *"fairchem"* ]]; then
            uv pip install huggingface_hub --system
          fi
          pytest -vv -ra -rs --cov=torch_sim --cov-report=xml ${{ matrix.model.test_path }}
 
      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@v5
        with:
          token: ${{ secrets.CODECOV_TOKEN }}
          slug: torchsim/torch-sim
 
  find-examples:
    timeout-minutes: 30
    runs-on: latchkey-small
    outputs:
      examples: ${{ steps.set-matrix.outputs.examples }}
    steps:
      - name: Check out repository
        uses: actions/checkout@v4
 
      - name: Find example scripts
        id: set-matrix
        run: |
          EXAMPLES=$(find examples -name "*.py" -not -path "examples/benchmarking/*" | jq -R -s -c 'split("\n")[:-1]')
          echo "examples=$EXAMPLES" >> $GITHUB_OUTPUT
 
  test-examples:
    timeout-minutes: 30
    needs: find-examples
    runs-on: latchkey-small
    strategy:
      fail-fast: false
      matrix:
        example: ${{fromJson(needs.find-examples.outputs.examples)}}
    steps:
      - name: Check out repository
        uses: actions/checkout@v4
 
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          cache: 'pip'
          python-version: '3.12'
 
      - name: Set up uv
        uses: astral-sh/setup-uv@v6
 
      - name: Run example
        if: ${{ !contains(matrix.example, 'fairchem') || github.event.pull_request.head.repo.fork == false }}
        env:
          HF_TOKEN: ${{ secrets.HUGGING_FACE_TOKEN }}
        run: |
          if [[ "${{ matrix.example }}" == *"fairchem"* ]]; then
            uv pip install huggingface_hub --system
          fi
          uv run --with-editable . ${{ matrix.example }}
 
  all-required-pass:
    timeout-minutes: 30
    if: always()
    needs: [test-core, test-examples]
    runs-on: latchkey-small
    steps:
      - name: Check all required jobs passed
        run: |
          if [[ "${{ needs.test-core.result }}" != "success" ]]; then
            echo "test-core failed or was cancelled"
            exit 1
          fi
          if [[ "${{ needs.test-examples.result }}" != "success" ]]; then
            echo "test-examples failed or was cancelled"
            exit 1
          fi
          echo "All required jobs passed"

What changed

Run on Latchkey managed runners with one line (runs-on), which apply the fixes below automatically and self-heal transient failures. This example uses latchkey-small; pick the runner size that fits the job.
Cache dependency installs on the setup step so they are served from cache.
Add a job timeout so a hung step cannot burn hours of runner time.

2 third-party actions are referenced by a movable tag. Pin them to the commit SHA (Latchkey resolves and applies this automatically) so a repointed tag cannot change what runs.

What Latchkey heals here

This workflow has steps that commonly fail on transient issues (network, registries, flaky browsers). On Latchkey managed runners they are detected, retried, and self-healed instead of failing your build:

Dependency installs

This workflow runs 5 jobs (51 with the matrix expanded) per trigger. On Latchkey the same minutes cost up to 58% less than GitHub-hosted, with zero queue time.

Actions used in this workflow

actions/checkout actions/setup-python astral-sh/setup-uv codecov/codecov-action