INTPYTHON-469 Document local testing setup (#55)

Author: blink1073

.github/scripts/check_diff.py

@@ -17,23 +17,15 @@
         raise ValueError("Max diff reached. Please manually run CI on changed libs.")
 
     for file in files:
-        if any(
-            file.startswith(dir_)
-            for dir_ in (
-                ".github/workflows",
-                ".github/tools",
-                ".github/actions",
-                ".github/scripts/check_diff.py",
-            )
-        ):
+        if any(file.startswith(dir_) for dir_ in (".github", "scripts")):
             # add all LIB_DIRS for infra changes
             dirs_to_run["test"].update(LIB_DIRS)
+            dirs_to_run["lint"].update(LIB_DIRS)
 
         if any(file.startswith(dir_) for dir_ in LIB_DIRS):
             for dir_ in LIB_DIRS:
                 if file.startswith(dir_):
                     dirs_to_run["test"].add(dir_)
-                if "langgraph-checkpoint-mongodb/tests" not in file:
                     dirs_to_run["lint"].add(dir_)
         elif file.startswith("libs/"):
             raise ValueError(

.github/workflows/_release.yml

@@ -26,6 +26,10 @@ jobs:
     if: github.ref == 'refs/heads/main'
     runs-on: ubuntu-latest
 
+    defaults:
+      run:
+        working-directory: ${{ inputs.working-directory }}
+
     outputs:
       pkg-name: ${{ steps.check-version.outputs.pkg-name }}
       version: ${{ steps.check-version.outputs.version }}
@@ -53,7 +57,6 @@ jobs:
       # https://github.com/pypa/gh-action-pypi-publish#non-goals
       - name: Build project for distribution
         run: uv build
-        working-directory: ${{ inputs.working-directory }}
 
       - name: Upload build
         uses: actions/upload-artifact@v4
@@ -64,7 +67,6 @@ jobs:
       - name: Check Version
         id: check-version
         shell: bash
-        working-directory: ${{ inputs.working-directory }}
         run: |
           echo pkg-name="$(hatch project metadata | jq -r .name)" >> $GITHUB_OUTPUT
           echo version="$(hatch version)" >> $GITHUB_OUTPUT
@@ -84,6 +86,9 @@ jobs:
       - build
       - test-pypi-publish
     runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ${{ inputs.working-directory }}
     steps:
       - uses: actions/checkout@v4
 
@@ -107,7 +112,6 @@ jobs:
 
       - name: Import published package
         shell: bash
-        working-directory: ${{ inputs.working-directory }}
         env:
           PKG_NAME: ${{ needs.build.outputs.pkg-name }}
           VERSION: ${{ needs.build.outputs.version }}
@@ -142,11 +146,9 @@ jobs:
 
       - name: Import test dependencies
         run: just install
-        working-directory: ${{ inputs.working-directory }}
 
       # Overwrite the local version of the package with the test PyPI version.
       - name: Import published package (again)
-        working-directory: ${{ inputs.working-directory }}
         shell: bash
         env:
           PKG_NAME: ${{ needs.build.outputs.pkg-name }}
@@ -158,30 +160,29 @@ jobs:
 
       - name: Run unit tests
         run: just tests
-        working-directory: ${{ inputs.working-directory }}
 
       - name: Start local Atlas
+        working-directory: .
         run: bash scripts/start_local_atlas.sh
 
       - name: Install Ollama
         run: curl -fsSL https://ollama.com/install.sh | sh
 
       - name: Run Ollama
+        working-directory: .
         run: |
           ollama serve &
           sleep 5    # wait for the Ollama server to be ready
-          ollama pull all-minilm:l6-v2
+          bash scripts/setup_ollama.sh
 
       - name: Run integration tests
         run: just integration_tests
-        working-directory: ${{ inputs.working-directory }}
 
       - name: Run unit tests with minimum dependency versions
         run: |
-          uv sync --python=${{ matrix.python-version }} --resolution=lowest-direct
+          uv sync --python=${{ env.PYTHON_VERSION }} --resolution=lowest-direct
           just test || git checkout uv.lock
           git checkout uv.lock
-        working-directory: ${{ inputs.working-directory }}
 
   publish:
     needs:

.github/workflows/_test.yml

@@ -52,14 +52,14 @@ jobs:
         run: curl -fsSL https://ollama.com/install.sh | sh
 
       - name: Run Ollama
+        working-directory: .
         run: |
           ollama serve &
           sleep 5    # wait for the Ollama server to be ready
-          ollama pull all-minilm:l6-v2
+          bash scripts/setup_ollama.sh
 
       - name: Run integration tests
         run: just integration_tests
-        working-directory: ${{ inputs.working-directory }}
 
       - name: Ensure the tests did not create any additional files
         shell: bash
@@ -77,4 +77,3 @@ jobs:
         run: |
           uv sync --python=${{ matrix.python-version }} --resolution=lowest-direct
           just test
-        working-directory: ${{ inputs.working-directory }}

.github/workflows/_test_release.yml

@@ -15,7 +15,9 @@ jobs:
   build:
     if: github.ref == 'refs/heads/main'
     runs-on: ubuntu-latest
-
+    defaults:
+      run:
+        working-directory: ${{ inputs.working-directory }}
     outputs:
       pkg-name: ${{ steps.check-version.outputs.pkg-name }}
       version: ${{ steps.check-version.outputs.version }}
@@ -43,7 +45,6 @@ jobs:
       # https://github.com/pypa/gh-action-pypi-publish#non-goals
       - name: Build project for distribution
         run: uv build
-        working-directory: ${{ inputs.working-directory }}
 
       - name: Upload build
         uses: actions/upload-artifact@v4
@@ -54,7 +55,6 @@ jobs:
       - name: Check Version
         id: check-version
         shell: bash
-        working-directory: ${{ inputs.working-directory }}
         run: |
           echo pkg-name="$(hatch project metadata | jq -r .name)" >> $GITHUB_OUTPUT
           echo version="$(hatch version)" >> $GITHUB_OUTPUT

CONTRIBUTING.md

@@ -35,6 +35,24 @@ Then verify the installation.
 just test
 ```
 
+In order to run the integration tests, you'll also need a `MONGODB_URI` for MongoDB Atlas, as well
+as either an `OPENAI_API_KEY` or a configured local version of [ollama](https://ollama.com/download).
+
+We have a convenience script to start a local Atlas instance, which requires `podman`:
+
+```bash
+scripts/start_local_atlas.sh
+```
+
+This will create a `.local_atlas_uri` file that has the `MONGODB_URI` set.  The `justfiles` are configured
+to read the environment variable from this file.
+
+If using `ollama`, we have a convenience script to download the library used in our tests:
+
+```bash
+scripts/setup_ollama.sh
+```
+
 ### Testing
 
 Unit tests cover modular logic that does not require calls to outside APIs.

scripts/setup_ollama.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+set -eu
+
+ollama pull all-minilm:l6-v2