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

4.8 KiB

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

# 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.