mirror of
https://github.com/xlionjuan/searxng-mcp-go.git
synced 2026-11-17 04:17:51 +00:00
119 lines
5.3 KiB
Markdown
119 lines
5.3 KiB
Markdown
# SearXNG Test Queries Reference
|
|
|
|
This document defines which queries to use when inspecting raw SearXNG JSON responses via `curl`, for the purpose of writing tests or verifying JSON parsing behavior.
|
|
|
|
Use this command pattern:
|
|
|
|
```bash
|
|
curl -s "http://localhost:8888/search?q=<query>&format=json" | jq '.<field>'
|
|
```
|
|
|
|
---
|
|
|
|
## Response Fields Overview
|
|
|
|
| Field | Expected Availability | Notes |
|
|
|-------|----------------------|-------|
|
|
| `query` | Always present | Echo of the search query |
|
|
| `number_of_results` | Always present (but often `0`) | Value is frequently 0 even when results exist; the field itself is always in the response |
|
|
| `answers` | Only for special queries | See [Answer Triggers](#answer-triggers) below |
|
|
| `infoboxes` | Entity queries | Search for company names, famous people, products (e.g., "apple inc", "nvidia", "elon musk") |
|
|
| `results` | Almost always present | Standard search results; empty only on no-match queries |
|
|
| `suggestions` | Usually present | Search suggestions; may be empty for very specific queries |
|
|
| `corrections` | Rarely present upstream | Excluded from this project per [ADR-005](adr/005-no-corrections.md); only relevant when verifying the upstream JSON shape, not the Go response |
|
|
| `unresponsive_engines` | Sometimes present | List of engines that failed to respond |
|
|
|
|
---
|
|
|
|
## Answer Triggers
|
|
|
|
Answers are computed **locally** by SearXNG's built-in answerers and plugins, not fetched from external search engines. They trigger when the query matches specific keywords.
|
|
|
|
### Answerers (built-in, run before engines)
|
|
|
|
| Trigger Keyword | Name | Description | Example |
|
|
|----------------|------|-------------|---------|
|
|
| `random` | Random value generator | Generates various random values | `random string`, `random int`, `random float`, `random sha256`, `random uuid`, `random color` |
|
|
| `min`, `max`, `avg`, `sum`, `prod`, `range` | Statistics functions | Compute min/max/avg/sum/prod/range of arguments | `avg 123 548 2.04 24.2` |
|
|
|
|
### Plugins (run as post-search hooks)
|
|
|
|
| Trigger Keyword | Name | Description | Example |
|
|
|----------------|------|-------------|---------|
|
|
| *(any math expression)* | Calculator | Parses and evaluates mathematical expressions | `2+2*3`, `(10+5)/3` |
|
|
| `md5`, `sha1`, `sha224`, `sha256`, `sha384`, `sha512` | Hash Plugin | Converts a string to hash digests | `sha512 The quick brown fox jumps over the lazy dog` |
|
|
| `ip` | Self Info | Shows the requester's IP address | `ip` |
|
|
| `user-agent` | Self Info | Shows the requester's User-Agent string | `user-agent` |
|
|
| `time`, `clock` | Timezone Plugin | Shows time in different timezones | `time Berlin`, `clock Los Angeles` |
|
|
|
|
---
|
|
|
|
## Test Query Recipes
|
|
|
|
> **Note on real-company queries in E2E tests.** Some E2E test suites
|
|
> (functional, MCP, error, stress, helpers) use real-company search terms such
|
|
> as `apple inc` and `framework computer inc` purely as stable sample search
|
|
> data. These names are chosen only because they reliably return a populated
|
|
> `results` array (and, in `apple inc`'s case, a Wikidata infobox) across the
|
|
> upstream engines. They are **not** canonical, preferred, or semantically
|
|
> meaningful queries; nothing in the project depends on, endorses, or treats
|
|
> these companies specially. Any equivalent stable real-company name would
|
|
> work just as well for parameter-iteration tests.
|
|
|
|
### One query per field
|
|
|
|
| Field to Test | Query | Expected Result |
|
|
|--------------|-------|-----------------|
|
|
| `answers` (hash) | `sha512 hello` | `answers[0].answer` = SHA512 digest |
|
|
| `answers` (self info) | `ip` | `answers[0].answer` = IP address |
|
|
| `answers` (timezone) | `time Berlin` | `answers[0].answer` = current time in Berlin |
|
|
| `answers` (statistics) | `avg 1 2 3 4 5` | `answers[0].answer` = average |
|
|
| `answers` (random) | `random uuid` | `answers[0].answer` = UUID |
|
|
| `infoboxes` | `apple inc` | `infoboxes[0].content` = company description |
|
|
| `results` | `golang tutorial` | `results[]` = array of search results |
|
|
| `suggestions` | `golang` | `suggestions[]` = array of search suggestions |
|
|
| `number_of_results` | Any query | Field always present (value often 0) |
|
|
|
|
### Multi-field query (all fields at once)
|
|
|
|
```
|
|
apple inc
|
|
```
|
|
|
|
Expected: `answers` (filtered if overlapping with infobox) + `infoboxes` + `results` + `suggestions`.
|
|
|
|
### Dedup behavior
|
|
|
|
DuckDuckGo's engine often puts the same Wikipedia summary in both `answers` and `infoboxes`. Our client deduplicates this: if an answer's text is a prefix of any infobox content, the answer is filtered out. Use `apple inc` to verify this behavior.
|
|
|
|
### Empty / edge case queries
|
|
|
|
| Query | Expected |
|
|
|-------|----------|
|
|
| `xyzzyqqq1234567890xyz` | No results, possibly no suggestions |
|
|
| Empty string | Validation error from client |
|
|
| Very long query (>500 chars) | Should handle gracefully |
|
|
|
|
---
|
|
|
|
## Quick Reference
|
|
|
|
```bash
|
|
# Test answers (hash)
|
|
curl -s "http://localhost:8888/search?q=sha512+hello&format=json" | jq '.answers'
|
|
|
|
# Test answers (IP)
|
|
curl -s "http://localhost:8888/search?q=ip&format=json" | jq '.answers'
|
|
|
|
# Test infoboxes
|
|
curl -s "http://localhost:8888/search?q=apple+inc&format=json" | jq '.infoboxes'
|
|
|
|
# Test suggestions
|
|
curl -s "http://localhost:8888/search?q=golang&format=json" | jq '.suggestions'
|
|
|
|
# Test results
|
|
curl -s "http://localhost:8888/search?q=golang+tutorial&format=json" | jq '.results | length'
|
|
|
|
# Full response keys
|
|
curl -s "http://localhost:8888/search?q=apple+inc&format=json" | jq 'keys'
|
|
```
|