Testing the URL Rewriter
Relevant source files
The following files were used as context for generating this wiki page:
The URL Rewriter is a critical component of the claude-code-docs plugin, functioning as a PreToolUse hook for the WebFetch tool. Its primary purpose is to intercept requests to code.claude.com/docs and rewrite them to point to their corresponding .md source files. This ensures that Claude receives clean Markdown content instead of the standard HTML application shell, improving the quality of the ingested documentation.
Sources: README.md:47-51, hooks/hooks.json:2-10
Testing Infrastructure
The testing suite for the URL Rewriter is implemented as a shell script that validates the logic within hooks/rewrite-docs-url.sh. It uses a mock environment to simulate WebFetch tool inputs and verifies the resulting JSON output against expected rewritten URLs or silent passes.
Test Utilities
The test suite defines two primary helper functions to automate the validation of rewrite logic:
expect_rewrite: Validates that a specific input URL is correctly transformed into a target Markdown URL while preserving other metadata like prompts.expect_silent: Ensures that URLs that should not be touched (e.g., external domains, files already ending in.md, or the documentation root) result in a silent exit (no output), allowing the original request to proceed normally.
Sources: hooks/rewrite-docs-url.test.sh:9-24
Data Flow for Testing
The following diagram illustrates how the test script interacts with the rewriter logic to validate transformations.
The testing process pipes a mock WebFetch JSON object into the shell script, which then uses jq to extract the URL and apply transformation logic.
Sources: hooks/rewrite-docs-url.test.sh:10-20, hooks/rewrite-docs-url.sh:7-12
Test Scenarios and Coverage
The test suite covers several critical URL patterns to ensure robust rewriting and to prevent regression.
Rewriting Rules
The rewriter target's specific URL structures under the code.claude.com/docs/ path.
| Input URL Pattern | Expected Transformation | Test Case Examples |
|---|---|---|
| Standard page | Append .md | .../agents -> .../agents.md |
| Trailing slash | Remove slash, append .md | .../agents/ -> .../agents.md |
| URL Fragments | Strip fragment, append .md | .../hooks#section -> .../hooks.md |
| Query Parameters | Strip parameters, append .md | .../hooks?foo=bar -> .../hooks.md |
| Nested paths | Maintain structure, append .md | .../agent-sdk/python -> .../agent-sdk/python.md |
Sources: hooks/rewrite-docs-url.test.sh:26-30, hooks/rewrite-docs-url.sh:18-25
Exclusion (Silent) Rules
To avoid breaking legitimate requests, certain patterns must be ignored by the rewriter.
- Files with extensions: URLs ending in
.md,.txt, or image extensions are left untouched. - Root paths: The documentation root (
/docs) or locale root (/docs/en) are not rewritten. - External domains: Any URL not belonging to
code.claude.com/docs/is ignored.
Sources: hooks/rewrite-docs-url.test.sh:32-38, hooks/rewrite-docs-url.sh:28-44
Implementation Details of the Rewriter
The logic being tested is contained within a Bash script that utilizes jq for JSON manipulation.
Tool Input Preservation
A key requirement of the rewriter is that it must not lose additional metadata attached to the tool call. The testing suite specifically checks that the prompt field survives the rewrite process. This is achieved by using jq to merge the updated URL back into the original .tool_input object.
# Example of the jq logic used for rewriting
jq --arg url "${path}.md" '{
hookSpecificOutput: {
hookEventName: "PreToolUse",
permissionDecision: "allow",
permissionDecisionReason: ("Rewrote Claude Code docs URL to markdown source: " + $url),
updatedInput: (.tool_input | .url = $url)
}
}'
Sources: hooks/rewrite-docs-url.sh:46-53, hooks/rewrite-docs-url.test.sh:41-44
Hook Execution Sequence
The rewriter operates within the Claude Code hook system. The following sequence diagram shows how the PreToolUse hook intercepts a WebFetch call.
This sequence ensures that the user is not prompted for permission again, as the hook returns permissionDecision: "allow".
Sources: hooks/hooks.json:4-11, hooks/rewrite-docs-url.sh:48-52
Summary
Testing the URL Rewriter ensures that the claude-code-docs plugin consistently provides Claude with high-quality Markdown documentation. By validating transformations of fragments, query strings, and nested paths—while strictly ignoring external or already formatted files—the test suite maintains the reliability of the documentation ingestion pipeline. The use of jq within the shell-based tests allows for precise verification of JSON payloads, ensuring that metadata like prompts are preserved during the rewrite process.
Sources: hooks/rewrite-docs-url.test.sh:47-48, README.md:55-60