[python] Python Integration Mock API Tests fail due to azure-http-specs version skew (pinned alpha.43 mock vs client regenerated from typespec-azure main)

[msyyc]

Summary

The Python Integration → Mock API Tests check (workflow .github/workflows/python-integration.yml) can fail with a body-validation error that is unrelated to the PR under test, due to a version skew between:

• the azure-http-specs mock server (pinned to @azure-tools/azure-http-specs@0.1.0-alpha.43 via http-client-python), and
• the generated client, which is regenerated from the Azure/typespec-azure main .tsp source checked out by the workflow.

When the spec source on typespec-azure main is newer than the pinned alpha.43 bundle, the client and the mock disagree and the tests fail.

Observed failure

Seen on PR #11272 (a change that only touches content-type header serialization, unrelated to ARM common-properties):

Run: https://github.com/microsoft/typespec/actions/runs/29883405836/job/88810730906

FAILED mock_api/azure/test_azure_arm_commonproperties.py::test_arm_resource_identifiers_create_or_replace
FAILED mock_api/azure/test_azure_arm_commonproperties.py::test_arm_resource_identifiers_get
FAILED mock_api/azure/asynctests/test_azure_arm_commonproperties_async.py::test_arm_resource_identifiers_create_or_replace
FAILED mock_api/azure/asynctests/test_azure_arm_commonproperties_async.py::test_arm_resource_identifiers_get

azure.core.exceptions.HttpResponseError: (None) Body provided doesn't match expected body:
  at $.properties: Key count mismatch: expected 4 but got 5. extra: [armIdWithGroupScope]

The generated client sends 5 properties (including armIdWithGroupScope); the mock server expects 4.

Root cause

The Build & Regenerate job pins only the compiled mock /dist to the http-client-python-resolved alpha.43, but the client is regenerated from the freshly checked-out typespec-azure main .tsp source:

• Mock server dist is overwritten with the pinned alpha.43 bundle:
  

  typespec/.github/workflows/python-integration.yml

  Lines 70 to 75 in f7ab083

  	- name: Use pinned http-specs versions
  	run: |
  	rm -rf core/packages/http-specs/dist
  	cp -r core/packages/http-client-python/node_modules/@typespec/http-specs/dist core/packages/http-specs/dist
  	rm -rf packages/azure-http-specs/dist
  	cp -r core/packages/http-client-python/node_modules/@azure-tools/azure-http-specs/dist packages/azure-http-specs/dist

• Client is regenerated right after, from the checked-out typespec-azure source:
  

  typespec/.github/workflows/python-integration.yml

  Lines 81 to 83 in f7ab083

  	- name: Regenerate
  	run: pnpm run regenerate
  	working-directory: packages/typespec-python

The pinned version:

• typespec/packages/http-client-python/package.json

  Line 111 in f7ab083

  "@azure-tools/azure-http-specs": "0.1.0-alpha.43",

  "@azure-tools/azure-http-specs": "0.1.0-alpha.43",

Meanwhile, armIdWithGroupScope was added to both the model and the mock in typespec-azure main by PR Azure/typespec-azure#4891 (2026-07-15), which is newer than the alpha.43 bundle:

• .tsp model (5th property):
  https://github.com/Azure/typespec-azure/blob/1081f0678431238b3451fdfd82dce3679e572f21/packages/azure-http-specs/specs/azure/resource-manager/common-properties/arm-resource-identifier.tsp#L68
• mock expected body (create-or-replace):
  https://github.com/Azure/typespec-azure/blob/1081f0678431238b3451fdfd82dce3679e572f21/packages/azure-http-specs/specs/azure/resource-manager/common-properties/mockapi.ts#L277-L296

So within typespec-azure main the spec is internally consistent (model and mock both have 5 fields). The skew is introduced only by the workflow, which mixes:

• client = typespec-azure main source (post-OpenAI - Ordering changes for internal constructors #4891 → 5 fields), and
• mock = pinned alpha.43 dist (pre-OpenAI - Ordering changes for internal constructors #4891 → 4 fields).

Impact

Any PR that only touches packages/http-client-python/** (which is what triggers this workflow) can get a red Mock API Tests check it did not cause, whenever typespec-azure main advances an azure-http-specs/http-specs spec beyond the pinned alpha.43 bundle. This blocks otherwise-green PRs (e.g. #11272).

Suggested fixes (pick one)

1. Bump the pin in packages/http-client-python/package.json for @azure-tools/azure-http-specs (and @typespec/http-specs) to a version that includes Add built-in service group extension support Azure/typespec-azure#4891, so the mock dist matches the spec source used for regeneration.
2. Regenerate the client from the same pinned bundle used for the mock, instead of from the checked-out typespec-azure main source — i.e. make both sides use one source of truth in python-integration.yml.
3. Do not pin the mock dist to the http-client-python-resolved version — build/use the mock from the same checked-out typespec-azure source used for regeneration, keeping client and mock in lockstep.

Option 2 or 3 removes the class of failure entirely; option 1 fixes the current occurrence.

Notes

• The http-client-python package's own unit/e2e tests (typespec - ci on Azure DevOps) are unaffected and pass; this is specific to the downstream typespec-python (Azure/typespec-azure) Mock API e2e run wired up by python-integration.yml.

[github-actions]

🎯 Issue Triage

The python-integration.yml workflow fails with body-validation errors unrelated to the PR under test, caused by a version skew between the pinned @azure-tools/azure-http-specs@0.1.0-alpha.43 mock server dist and the client regenerated from the newer typespec-azure main source.

Category: Bug

Area: emitter:client:python

🔍 Analysis

• Affected component: .github/workflows/python-integration.yml + packages/http-client-python/package.json
• Root cause: The workflow overrides the mock server dist with the pinned alpha.43 bundle but regenerates the client from the live typespec-azure main checkout. When typespec-azure main adds new fields (e.g., armIdWithGroupScope via Add built-in service group extension support Azure/typespec-azure#4891 on 2026-07-15), the client and mock go out of sync, causing false-positive failures.
• Impact: Any PR touching packages/http-client-python/** can get a spurious red check, blocking otherwise-green work (e.g., PR [python] fix: omit content-type header when optional body is absent #11272).
• Three candidate fixes are well-identified in the issue:
  1. Bump the @azure-tools/azure-http-specs pin to include the new spec changes (tactical fix).
  2. Regenerate the client from the pinned bundle instead of typespec-azure main (structural fix).
  3. Drop the dist pin and build the mock from the same typespec-azure checkout used for regeneration (structural fix).

📝 Suggested next steps

• Apply fix option 2 or 3 in python-integration.yml to permanently remove the class of failure.
• As an immediate unblock, bump @azure-tools/azure-http-specs in packages/http-client-python/package.json to a version ≥ the one containing Add built-in service group extension support Azure/typespec-azure#4891.

Generated by Agentic Triage