searxng-mcp-go/docs/agents/test-server.md
XLion 1afa9612c3
docs: align documentation with code behavior (issues #547-#551) (#554)
* docs: align documentation with code behavior (issues #547-#551)

- INSTALL.md: drop SEARXNG_MAX_RETRIES=-1 from the unparsable-value
  example list; cross-reference the hard-error semantic path
- PROMPT_INJECTION_SAFETY.md: mark Option A (warning header + warning
  field) as implemented, referencing #448 and #50
- MCP_TESTING.md: E2E binary is built once into a package-level cache,
  not per test; e2eMCPEnv lives in e2e_helper_test.go; goroutine-leak
  guard is suite-wide, not stress-file-specific
- e2e-tests.md: fix workflow line citations (:87, :104)
- verification.md: drop misleading '(except E2E)' qualifier; narrow the
  E2E-workflow coverage claim for exit-code tests
- test-server.md: add missing test-server-pid-helper recipe row
- .env.example: document SEARXNG_ALLOW_GET_FALLBACK opt-in
- MCP_TOOLS.md: include 'failed to execute search request' segment in
  the network-failure error format
- OUTPUT_FORMAT.md: sync Example 1 count line with the (showing N) format
- adr/014: suppression was relocated to searchWithRetries, not removed
- CONTEXT.md: note empty-text answers are dropped before the engine gate

* docs: address review findings on doc accuracy (P2 items)

- INSTALL.md: SEARXNG_MAX_RETRIES format is an integer in the range
  0-20, not 'non-negative integer' — -1 parses and is rejected by
  SetMaxRetries, so the old wording conflated syntax and semantics
- MCP_TESTING.md: example and E2E_MCP_BINARY section no longer claim a
  per-test build; list e2e_mockserver_test.go among the ungated CLI
  tests that build per-test via buildTestBinary
- CONTEXT.md: dedup description notes the early return when no
  non-empty infobox text exists (original answers returned unchanged)

* docs: fix remaining dedup and E2E_MCP_BINARY wording (P2)

- CONTEXT.md: example dialogue no longer claims non-DuckDuckGo
  answers are never touched; empty answers are dropped before the
  engine check when dedup runs, matching the Search Behavior entry
- test-server.md, verification.md: E2E_MCP_BINARY skips the MCP E2E
  package-level build, not the ungated CLI per-test builds

* docs: scope dedup pass-through claim to non-empty answers

SEARXNG_ANSWER_DEDUP.md and the DeduplicateAnswers doc comment both
claimed non-DuckDuckGo answers always pass through. In fact, when dedup
runs (non-empty infobox content exists), empty-text answers are dropped
before the engine gate; only non-empty non-DuckDuckGo answers pass
through. Aligns both with the implementation in deduplicate.go.

* docs: fix dedup algorithm order in SEARXNG_ANSWER_DEDUP.md

Document the empty-text filter running before the engine gate (matching
deduplicate.go) and add the early-return precondition; sync the Edge
Cases table so retain behavior is scoped to non-empty answers.

* docs: qualify empty-answer drop with early-return precondition

SEARXNG_ANSWER_DEDUP.md edge-case row and the deduplicateAnswers
wrapper comment both stated empty-text answers are always filtered.
When no non-empty infobox exists the implementation early-returns the
original answers unchanged; scope the drop to dedup runs only.
2026-08-11 05:20:47 +08:00

103 lines
4.8 KiB
Markdown

# Local SearXNG Test Server
Use this guide for E2E and integration tests that require a live local SearXNG
instance. The `just` recipes in the root `justfile` are the primary interface;
the shell scripts under `searxng-server-test/` are implementation details.
## Quick Start
```bash
# One-time submodule initialization
git submodule update --init --depth 1 searxng-server-test/searxng
# One-time setup: creates venv, installs deps, generates settings.yml
just test-server-setup
# Day-to-day
just test-server-start
export SEARXNG_URL=http://127.0.0.1:8888
go test -tags=e2e -run TestMCPStdioE2E -count=1 .
just test-server-stop
```
## Recipes
| Command | Purpose |
|---|---|
| `just test-server-setup` | One-time setup or reset |
| `just test-server-deps-sync` | Sync pyproject.toml deps from upstream SearXNG requirements; run after submodule update |
| `just test-server-start` | Start background server and wait for readiness |
| `just test-server-status` | Report live / degraded / stale / dead / orphan |
| `just test-server-logs` | Tail `searxng-server-test/searxng.log` |
| `just test-server-stop` | Stop background instance; uses SIGTERM then SIGKILL fallback |
| `just test-server-restart` | Stop then start |
| `just test-server-start-fg` | Foreground mode for humans only; do not use from agents or CI |
| `just test-server-pid-helper` | Shell unit tests for `is_searxng_pid` |
## Underlying Scripts
Agents should prefer `just` recipes. These scripts are listed for debugging
script changes or ownership checks.
| Script | Purpose |
|---|---|
| `searxng-server-test/00-setup.sh` | One-time venv, deps, and `settings.yml` setup |
| `searxng-server-test/01-start-bg.sh` | Background start with PID tracking and readiness polling |
| `searxng-server-test/01-start-fg.sh` | Foreground start; do not use from agents or CI |
| `searxng-server-test/02-stop.sh` | Stop background instance; `--force` kills orphans |
| `searxng-server-test/03-status.sh` | Report live / stale / dead / orphan state |
| `searxng-server-test/50-sync-searxng-requirement-to-pyproject.sh` | Re-import upstream requirements into pyproject.toml and refresh uv.lock |
| `searxng-server-test/lib-searxng-pid.sh` | Shared `is_searxng_pid` ownership check |
| `searxng-server-test/test-pid-helper.sh` | Shell unit tests for `is_searxng_pid` |
## Key Details
- The server runs on `http://127.0.0.1:8888`.
- Set `SEARXNG_URL=http://127.0.0.1:8888` before running E2E tests.
- `01-start-bg.sh` polls readiness for up to 30 seconds, then exits while the
server remains detached in the background.
- `settings.yml` is generated from SearXNG defaults, enables JSON format,
enables the yahoo / bing / ddg-definitions engines, and generates a random
secret key.
- Background state is tracked in `searxng-server-test/.bg-pid` and
`searxng-server-test/searxng.log`; both are kept out of git.
- Check `searxng-server-test/searxng.log` first when E2E tests fail with
connection or timeout errors.
- Starting the server a second time without stopping it first is rejected; use
`just test-server-restart`.
## Stress Testing
The stress and concurrency tests use the same test server setup. The
`stress` build tag groups in-process concurrency tests with the live-server
E2E stress tests; the combined `e2e stress` tag is required for the latter.
| Command | Scope |
|---|---|
| `go test -tags=stress -race ./...` | Internal concurrency tests; no SearXNG required |
| `SEARXNG_URL=http://127.0.0.1:8888 go test -tags='e2e stress' -run 'TestMCPStress' -race -count=1 -timeout=900s .` | Live-server E2E stress suite; requires a running test server |
| `.github/workflows/e2e-stress.yml` | Manual CI workflow dispatch |
Use the same setup and lifecycle as the regular E2E tests: run
`just test-server-setup` once, then `just test-server-start` and
`just test-server-stop` around the stress run. The CI workflow uses
`E2E_MCP_BINARY=./searxng-mcp-go` to skip the MCP E2E package-level build.
## Pitfalls
- `searxng-server-test/searxng/` is a git submodule registered in the root
`.gitmodules`. Do not run `git init` or `git submodule add` inside
`searxng-server-test/`.
- Do not use `searx/limiter.toml` from the production template. The generated
test settings use `limiter: false`.
- The repo's default settings have `valkey.url: false`; do not use
`utils/templates/etc/searxng/settings.yml`, which enables valkey.
- When testing with granian, pass `--interface wsgi`.
- Never run `01-start-fg.sh` from agents or CI. It blocks the calling shell
until killed.
- `.bg-pid` can go stale if an agent shell dies. Inspect with
`pgrep -f 'searx/webapp\\.py|searx\\.webapp:app'`, then use `just test-server-stop` or the stop
script with `--force` if needed.
- A recorded PID can be recycled by an unrelated process. The start, stop, and
status scripts verify that argv contains `searx/webapp.py` or `searx.webapp:app`; do not bypass that
check.