mirror of
https://github.com/xlionjuan/searxng-mcp-go.git
synced 2026-11-17 04:17:51 +00:00
* 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.
103 lines
4.8 KiB
Markdown
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.
|