* 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.
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:8888before running E2E tests. 01-start-bg.shpolls readiness for up to 30 seconds, then exits while the server remains detached in the background.settings.ymlis 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-pidandsearxng-server-test/searxng.log; both are kept out of git. - Check
searxng-server-test/searxng.logfirst 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 rungit initorgit submodule addinsidesearxng-server-test/.- Do not use
searx/limiter.tomlfrom the production template. The generated test settings uselimiter: false. - The repo's default settings have
valkey.url: false; do not useutils/templates/etc/searxng/settings.yml, which enables valkey. - When testing with granian, pass
--interface wsgi. - Never run
01-start-fg.shfrom agents or CI. It blocks the calling shell until killed. .bg-pidcan go stale if an agent shell dies. Inspect withpgrep -f 'searx/webapp\\.py|searx\\.webapp:app', then usejust test-server-stopor the stop script with--forceif needed.- A recorded PID can be recycled by an unrelated process. The start, stop, and
status scripts verify that argv contains
searx/webapp.pyorsearx.webapp:app; do not bypass that check.