search-web-api 1.0.169 → 1.0.170

package/README.md

@@ -308,3 +308,27 @@ app/
 │   └── engine-descriptions.ts
 └── index.ts          # Main entry point
 ```
+
+## Testing
+
+```bash
+bun run test           # the suites CI gates on — no network
+bun run test:coverage  # the same, with coverage (writes coverage/lcov.info)
+bun run test:live      # adds the suites that call the real search engines
+```
+
+`bun run test` runs only deterministic suites: `test/sources-unit.test.ts`
+exercises every engine against mocked responses, and
+`src/search/__tests__/public-searxng.test.ts` covers the SearXNG client.
+
+`test/api.test.ts`, `test/search.test.ts`, `test/sources.test.ts`,
+`test/engine-health-suite.test.ts` and `test/autocomplete-ai.test.ts` really do
+query the upstream engines, so whether they pass depends on third-party
+availability and on whether an engine feels like rate-limiting your IP. They
+are excluded unless `RUN_LIVE_TESTS=1` is set — which is what `test:live` does
+— and they are the right thing to run by hand when you change an engine, since
+a mock only proves the parser still matches the fixture.
+
+`examples/autocomplete-engines.ts` (`bun run example:autocomplete`) prints what
+each autocomplete backend answers. It asserts nothing, so it is an example
+rather than a suite.

package/{test/autocomplete-engines.test.ts → examples/autocomplete-engines.ts}

@@ -3,6 +3,10 @@
  *
  * Demonstrates how to use the autocomplete functionality
  * to get search query suggestions from various search engines.
+ *
+ * Run it with `bun run example:autocomplete`. It calls the live engines and
+ * prints what they answer; it asserts nothing, which is why it lives here and
+ * not in `test/` — Vitest fails a `*.test.ts` file that declares no suite.
  */
 
 import {

package/package.json

@@ -2,7 +2,7 @@
   "name": "search-web-api",
   "description": "70+ search engines across 10 categories and Scrape Extract API",
   "type": "module",
-  "version": "1.0.169",
+  "version": "1.0.170",
   "author": "vtempest",
   "license": "rights.institute/PROSPER",
   "repository": {
@@ -26,7 +26,9 @@
     "dev": "bun --watch demo/index.ts",
     "start": "bun demo/index.ts",
     "test": "vitest run",
-    "test:coverage": "vitest run --coverage"
+    "test:live": "RUN_LIVE_TESTS=1 vitest run",
+    "test:coverage": "vitest run --coverage",
+    "example:autocomplete": "bun examples/autocomplete-engines.ts"
   },
   "dependencies": {
     "@huggingface/transformers": "^4.2.0",

package/test/sources-unit.test.ts

@@ -606,7 +606,10 @@ function getMockForUrl(url: string, options?: RequestInit): Response {
   if (u.includes("google.com/search") && !u.includes("tbm=isch") && !u.includes("news.google.com")) return makeMockResponse({ html: GOOGLE_HTML });
   if (u.includes("bing.com/search")) return makeMockResponse({ html: BING_HTML });
   if (u.includes("duckduckgo.com/html")) return makeMockResponse({ html: DUCKDUCKGO_HTML });
-  if (u.includes("search.yahoo.com/search")) return makeMockResponse({ html: YAHOO_HTML });
+  // `news.search.yahoo.com` ends in this host, so the news engine would be
+  // served the general-search page and parse nothing out of it — the same
+  // trap the `news.google.com` guard above sidesteps.
+  if (u.includes("search.yahoo.com/search") && !u.includes("news.search.yahoo.com")) return makeMockResponse({ html: YAHOO_HTML });
   if (u.includes("api.qwant.com")) return makeMockResponse({ json: { data: { result: { items: [{ url: "https://example.com", title: "Qwant Title", desc: "Qwant description." }] } } } });
   if (u.includes("startpage.com/sp/search")) return makeMockResponse({ html: STARTPAGE_HTML });
   if (u.includes("search.brave.com")) return makeMockResponse({ html: BRAVE_HTML });

package/vitest.config.ts

@@ -1,15 +1,37 @@
-import { defineConfig } from 'vitest/config';
+import { defineConfig, configDefaults } from 'vitest/config';
+
+/**
+ * Suites that call the real search engines over the network. Whether they pass
+ * is decided by third-party availability and by whether the engine feels like
+ * rate-limiting the runner's IP that minute, so they are opt-in
+ * (`bun run test:live`) instead of gating every push. `test/sources-unit.test.ts`
+ * covers the same engines against mocked responses and does gate CI.
+ */
+const LIVE_NETWORK_SUITES = [
+    'test/api.test.ts',
+    'test/autocomplete-ai.test.ts',
+    'test/engine-health-suite.test.ts',
+    'test/search.test.ts',
+    'test/sources.test.ts'
+];
+
+const includeLive = process.env.RUN_LIVE_TESTS === '1';
 
 export default defineConfig({
     test: {
         globals: true,
         environment: 'node',
+        exclude: [
+            ...configDefaults.exclude,
+            ...(includeLive ? [] : LIVE_NETWORK_SUITES)
+        ],
         coverage: {
             provider: 'v8',
-            reporter: ['text', 'json', 'html'],
+            reporter: ['text', 'json', 'html', 'lcov'],
             exclude: [
                 'node_modules/**',
                 'dist/**',
+                'examples/**',
                 '**/*.test.ts',
                 '**/__tests__/**'
             ]