Add snapshot of the SDK for snapshot tests

.gitattributes

@@ -0,0 +1,13 @@
+# Collapse machine-produced files in pull request diffs and exclude them from
+# the repository's language statistics.
+#
+# Deliberately NOT marked `-diff`: `make check-snapshots` fails when generated
+# output drifts, and reviewing that diff is the point. These files stay
+# diffable, just collapsed by default.
+
+# Vendored: synced verbatim from fragment-dev/graphql-queries by the
+# updateSDKQueries workflow. Never edited here.
+tests/template-schema/** linguist-vendored=true
+
+# Generated: produced by `make snapshots` from the sibling queries.graphql.
+tests/snapshots/*/sdk/** linguist-generated=true

.github/workflows/tests.yml

@@ -35,3 +35,28 @@ jobs:
 
       - name: Run tests
         run: poetry run pytest -v
+
+  # Regenerates the clients in tests/snapshots/ and fails if the output differs
+  # from what is committed. Needs no credentials -- codegen only downloads the
+  # public GraphQL schema -- so it is a separate job and still runs on forks.
+  snapshots:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
+        name: Checkout fragment-python
+
+      - name: Use Python 3.10.14
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: '3.10.14'
+
+      - name: Install dependencies
+        run: |
+          pip install poetry
+          poetry install --with dev
+
+      - name: Check generated clients match snapshots
+        run: make check-snapshots

.github/workflows/updateSDKQueries.yml

@@ -43,6 +43,17 @@ jobs:
           mkdir queries
           cp ../graphql-queries/queries.graphql fragment/std_queries/queries.graphql
 
+      # The template Schema is the source of truth the tests build against:
+      # schema.json is what they store, and queries.graphql is valid codegen
+      # input for the same Schema. Mirrored wholesale rather than file-by-file so
+      # that files removed upstream also disappear here. Do not edit the copy in
+      # tests/template-schema -- the next sync overwrites it.
+      - name: Copy template Schema
+        working-directory: ./fragment-python
+        run: |
+          rm -rf tests/template-schema
+          cp -R ../graphql-queries/template-schema tests/template-schema
+
       - name: Generate SDK
         working-directory: ./fragment-python
         run: |
@@ -55,7 +66,7 @@ jobs:
           path: ./fragment-python
           token: ${{ steps.generate-token.outputs.token }}
           commit-message: 'Update Python SDK queries'
-          title: 'Update Python SDK queries'
+          title: 'Update Python queries and snapshots'
           base: 'dev'
           branch: update-sdk-queries/${{ github.run_id }}
           body: >

Makefile

@@ -1,4 +1,10 @@
-.PHONY: lint test
+.PHONY: lint test snapshots check-snapshots
+
+# Each tests/snapshots/*/ holds a queries.graphql and the client generated from
+# it, checked in. The pair is a regression guard: a change to codegen that alters
+# generated output shows up as a reviewable diff instead of silently.
+SNAPSHOT_DIRS := $(sort $(dir $(wildcard tests/snapshots/*/queries.graphql)))
+SNAPSHOT_PACKAGE := sdk
 
 install:
 	poetry install --with dev
@@ -19,6 +25,36 @@ typecheck:
 test:
 	poetry run pytest
 
+# Overwrite the checked-in snapshots with freshly generated clients. Run this
+# deliberately after an intended codegen change, then review the diff before
+# committing it.
+snapshots:
+	@for dir in $(SNAPSHOT_DIRS); do \
+		echo "Regenerating $$dir$(SNAPSHOT_PACKAGE)"; \
+		rm -rf "$$dir$(SNAPSHOT_PACKAGE)"; \
+		poetry run fragment-python-client-codegen \
+			--input-dir="$$dir" \
+			--target-package-name=$(SNAPSHOT_PACKAGE) \
+			--output-dir="$$dir" || exit 1; \
+	done
+	poetry run isort tests/snapshots/
+	poetry run black tests/snapshots/
+
+# Regenerate in place and fail if anything changed. Used in CI so generated
+# output cannot drift from the committed snapshots.
+check-snapshots: snapshots
+	@untracked="$$(git ls-files --others --exclude-standard -- tests/snapshots)"; \
+	if ! git diff --quiet -- tests/snapshots || [ -n "$$untracked" ]; then \
+		echo ""; \
+		echo "Generated client differs from the committed snapshots."; \
+		echo "If the change is intended, run 'make snapshots' and commit the result."; \
+		echo ""; \
+		git --no-pager diff --stat -- tests/snapshots; \
+		[ -n "$$untracked" ] && printf 'untracked:\n%s\n' "$$untracked"; \
+		exit 1; \
+	fi
+	@echo "Snapshots up to date."
+
 build: install
 	poetry run fragment-python-client-codegen --input-dir=queries/ --target-package-name=sdk --output-dir fragment/
 	poetry run fragment-python-client-codegen --input-dir=queries/ --target-package-name=sync_sdk --output-dir fragment/ --sync