You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 571e2b3
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: .claude/skills/pre-push-gate/SKILL.md
+34-1Lines changed: 34 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -75,7 +75,8 @@ unquoted `#` or `:` in a `description`.
75
75
`verify:skills:cli` is the authoritative validator. It fetches the pinned
76
76
Claude Code CLI with `npx` when the installed one is a different version, so it
77
77
**fails offline**. (`validate:py`'s `sync` step is the other stage that can:
78
-
`uv sync --locked` downloads when a server's environment is missing or stale.)
78
+
`uv sync --locked` downloads when a server's environment is missing or stale.
79
+
`coverage:py` opens with the same sync, a no-op once `validate:py` has run.)
79
80
80
81
### `verify:typecheck-coverage`
81
82
@@ -205,6 +206,38 @@ the last `[validate:py] <server>: <step>` line above it. Re-run one server with
205
206
206
207
`uv: command not found` means `uv` is not installed. Never substitute `pip`.
207
208
209
+
### `coverage:py`
210
+
211
+
The Python per-file coverage gate: every file each server measures must reach
212
+
**90% on lines and 90% on branches**. The summary names the server, the step,
213
+
and for a shortfall each file and dimension below 90:
214
+
215
+
```
216
+
FAIL time — per-file check (2 below 90%)
217
+
src/time/src/mcp_server_time/server.py: lines 84.2% (75/89) is below 90%
218
+
src/time/src/mcp_server_time/server.py: branches 78.5% (11/14) is below 90%
219
+
```
220
+
221
+
Re-run one server with `npm run coverage:py -- <server>`. The per-file table
222
+
above the summary gives both figures for every file, and coverage.py's own
223
+
report above that (`term-missing`) lists the uncovered lines and partial
224
+
branches (`120->124` is the jump from line 120 to 124 never taken).
225
+
226
+
| Step | Fix |
227
+
| --- | --- |
228
+
|`sync`| As for `validate:py`: run `uv lock` in that server and commit the lockfile |
229
+
|`pytest --cov`| A test failed, so no verdict was reached; fix it as for `validate:py`'s `pytest`. `unrecognized arguments: --cov` means `pytest-cov` is missing from the server's dev dependencies |
230
+
|`per-file check`, "below 90%" | Write tests for the lines and branches the report lists. Drive the server in-process through a `ClientSession` where you can (`/testing`) |
231
+
|`per-file check`, "was not written" or "measured no files" | The run produced no usable `coverage.json`: check the server's `[tool.coverage.run]` (`branch = true`, `source` naming its package) |
232
+
|`per-file check`, "not measured with branch coverage" or "no covered_branches/num_branches" |`branch = true` is missing from `[tool.coverage.run]`. The check refuses such a report rather than counting every file's zero branches as 100% |
233
+
234
+
**Never lower the gate**, and never drop a file from `source` to clear it.
235
+
Code that genuinely cannot run (a guard the types already rule out, a branch
236
+
the SDK's input validation makes unreachable) is marked at the source with
237
+
`# pragma: no cover # <reason>`; every pragma carries its reason
238
+
(`AGENTS.md`**Always test new or modified code**). A pragma on a line that is
239
+
merely awkward to test is not justified; write the test.
240
+
208
241
### `smoke`
209
242
210
243
`smoke — FAIL <server> over <transport>` followed by the reason and the tail
|`fetch`, `git`, `time`|`src/<server>/tests/`|`test_<subject>.py`| pytest, with `pytest-asyncio` (`asyncio_mode = "auto"`) |
31
31
| Root tooling |`scripts/`, beside the script |`<name>.test.mjs`|`node --test`|
32
32
33
33
Each vitest config includes only `**/__tests__/**/*.test.ts`, so a test file
@@ -41,9 +41,9 @@ connection harness does (`__tests__/harness.ts` in `everything`,
41
41
| Server | How its tests reach the code |
42
42
| --- | --- |
43
43
|`everything`, `filesystem`, `memory`, `sequentialthinking`| An SDK `Client` connected to the server's `createServer()` over `InMemoryTransport`, in the vitest process, through the server's own harness, plus unit tests of helper modules such as `lib.ts`. `everything` drives its stdio, SSE and Streamable HTTP transports in-process too; the other three have one thin spawn smoke of the built `dist/index.js`|
44
-
|`fetch`, `git`, `time`|Direct calls on the functions in `server.py`, with `unittest.mock`|
44
+
|`fetch`, `git`, `time`|A `ClientSession` linked in-process to the real `serve()` over in-memory streams (below), plus direct calls on the pure functions in `server.py`|
45
45
46
-
No Python test opens a `ClientSession` yet.
46
+
No TypeScript test uses an in-memory transport yet.
47
47
48
48
## Choosing a harness for a new test
49
49
@@ -162,44 +162,71 @@ in the transport's `env` option (`MEMORY_FILE_PATH`, say), since the child
162
162
inherits only the SDK's default safelist (`PATH`, `HOME`, `USER` and the
163
163
like).
164
164
165
-
### Python: `ClientSession` over stdio
165
+
### Python: `ClientSession` over in-memory streams, in-process
166
166
167
-
Each Python server constructs its `Server` inside `serve()`, so it cannot be
168
-
handed to an in-memory session. A protocol-level test spawns the module and
169
-
talks to it through the SDK's stdio client:
167
+
Each Python server builds its `Server` inside `serve()` and serves it over the
168
+
`stdio_server()` it imports into `server.py`. A test replaces that one name
169
+
with a context manager that yields the server side of a pair of in-memory
170
+
streams, runs the real `serve()` in a task group, and opens a `ClientSession`
171
+
on the client side. No process, no build, and the SDK's input validation and
172
+
error mapping run exactly as they do for a real client:
170
173
171
174
```python
172
-
import sys
175
+
from contextlib import asynccontextmanager
176
+
from typing import Any, AsyncIterator
173
177
174
178
import anyio
175
-
from mcp import ClientSession, StdioServerParameters
result =await session.call_tool("get_current_time", {"timezone": "UTC"})
207
+
assert result.isError isFalse
208
+
```
197
209
198
-
How an async test is written differs by server, because the dev dependencies
199
-
do: `fetch` has `pytest-asyncio` with `asyncio_mode = "auto"`, so an
200
-
`async def test_…` just works. `git` and `time` do not have it; wrap the
201
-
coroutine in `anyio.run(...)` as above (`git`'s `serve()` test does), rather
202
-
than adding a dependency for one test.
210
+
-**Patch the name `server.py` looks up** (`mcp_server_<name>.server.stdio_server`),
211
+
not `mcp.server.stdio.stdio_server`: `server.py` imported the function, so
212
+
the module attribute is what `serve()` calls.
213
+
-**Cancel the task group after the session closes.**`serve()` runs until its
214
+
streams end, so without the cancel the test never returns.
215
+
-**Assert on the wire shape where you can**, for example
216
+
`result.model_dump(by_alias=True, mode="json")`, rather than on Python
217
+
attribute names: the SDK v2 port (#4851) renames them, and a wire-level
218
+
assertion survives it.
219
+
-**No network in a test.**`fetch` replaces `httpx.AsyncClient` with one on an
220
+
`httpx.MockTransport`; `git` works against a temporary repository its
221
+
fixture creates and closes before removing.
222
+
223
+
`pytest-asyncio` with `asyncio_mode = "auto"` is a dev dependency of all three,
224
+
so an `async def test_…` runs as it stands.
225
+
226
+
A subprocess test over stdio (`StdioServerParameters(command=sys.executable,
227
+
args=["-m", "mcp_server_<name>"])` with `mcp.client.stdio.stdio_client`) is
228
+
kept to a thin smoke of the entry point. coverage.py does not measure a child
229
+
process, so code reached only that way reads as uncovered.
203
230
204
231
## Tests that pin a known bug
205
232
@@ -236,8 +263,10 @@ In Python the same text follows `#`. A bug with no issue yet reads
236
263
| One TypeScript server's coverage gate |`npm run coverage -w src/<server>` (see below) |
237
264
| One TypeScript server's whole chain |`npm run validate -w src/<server>` (format check, lint, typecheck, build, test) |
238
265
| One Python server |`uv run pytest` in `src/<server>`|
239
-
| One Python test |`uv run pytest <path to the test file>::<name>` in `src/<server>` (for example `tests/test_server.py::test_git_checkout_existing_branch`, or `test/time_server_test.py::…` in `time`) |
266
+
| One Python test |`uv run pytest <path to the test file>::<name>` in `src/<server>` (for example `tests/test_server.py::test_git_checkout_existing_branch`) |
240
267
| One Python server's whole chain |`npm run validate:py -- <server>`|
268
+
| One Python server's coverage gate |`npm run coverage:py -- <server>` at the root |
269
+
| Every Python server's coverage gate |`npm run coverage:py` at the root |
241
270
| Root tooling |`npm run test:scripts`|
242
271
243
272
`npm run typecheck -w src/<server>` is the only step that typechecks the test
@@ -277,13 +306,30 @@ Clearing a red file:
277
306
- Never lower a threshold, drop `perFile`, or add a file to the coverage
278
307
`exclude` to get green.
279
308
309
+
**The Python servers' coverage is a gate.**`npm run coverage:py -- <server>`
310
+
runs, in `src/<server>`:
311
+
312
+
```sh
313
+
uv run --frozen pytest --cov --cov-report=term-missing --cov-report=json
314
+
```
315
+
316
+
which prints coverage.py's report (the missing lines and partial branches)
317
+
and writes `coverage.json` (ignored by git). `scripts/lib/py-coverage.mjs` then
318
+
checks **every file** in it: at least 90% of its lines and 90% of its branches,
319
+
each file on its own. What is measured is the server's `[tool.coverage.run]`
320
+
(`branch = true`, `source` set to its package). `local:gate` and CI's
321
+
**Coverage \<server\>** job both run it. It is kept out of the plain
322
+
`uv run pytest` loop, which stays fast and uninstrumented.
323
+
324
+
A line or branch that genuinely cannot run is marked
325
+
`# pragma: no cover # <reason>`, with the reason on the same line; never
326
+
lower the gate. Diagnosing a red run is `/pre-push-gate`.
327
+
280
328
⚠️ **A spawned server is invisible to the report.** v8 coverage measures the
281
329
vitest process, not a child it starts, so code reached only through a spawn
282
330
smoke reads as uncovered. That is why behavior is tested in-process: a file
283
331
whose only test spawns it cannot clear the gate.
284
332
285
-
The Python servers have no coverage tooling yet (#4855).
286
-
287
333
## Error output
288
334
289
335
A test that expects an error keeps it off the console. Spy on the logger for
0 commit comments