|
| 1 | +--- |
| 2 | +name: test-sdk |
| 3 | +description: Run a full end-to-end test of the scrapegraph-js SDK against the live API using an API key the user provides at invocation. Exercises every public method on the ScrapeGraphAI client. Use when the user asks to "test the SDK", "run SDK tests", or "/test-sdk". |
| 4 | +--- |
| 5 | + |
| 6 | +# Test the scrapegraph-js SDK |
| 7 | + |
| 8 | +## Hard rules |
| 9 | + |
| 10 | +1. **Never push directly to `main`.** Do not run `git push`, `git push origin main`, or any force-push against `main`. Do not commit to `main` on the user's behalf. If changes are needed, create a branch and open a PR — never bypass review on the SDK's main branch. |
| 11 | +2. **Never skip git hooks.** No `--no-verify`, no `--no-gpg-sign`. |
| 12 | +3. **Use the API key the user provides in this turn.** Do not read `SGAI_API_KEY` from the shell environment or from `.env`. Do not hardcode it into any file. Do not commit it. Do not echo it into long-lived logs. |
| 13 | +4. **If the user did not include an API key**, stop and ask for one before doing anything else. |
| 14 | + |
| 15 | +## How to use the key |
| 16 | + |
| 17 | +Pass it inline for the duration of each command: |
| 18 | + |
| 19 | +```bash |
| 20 | +SGAI_API_KEY="<key-from-user>" bun run <script> |
| 21 | +``` |
| 22 | + |
| 23 | +Do not `export` it into the shell. Do not write it to `.env`, a test fixture, or any file that could be committed. |
| 24 | + |
| 25 | +## What to test |
| 26 | + |
| 27 | +Exercise every public method on the `ScrapeGraphAI()` client. The list (from `CLAUDE.md`): |
| 28 | + |
| 29 | +- `sgai.scrape()` — AI extraction from URL |
| 30 | +- `sgai.extract()` — extraction from raw HTML/text |
| 31 | +- `sgai.search()` — web search + extraction |
| 32 | +- `sgai.crawl.start()` → `sgai.crawl.get()` — start a crawl and poll until it terminates |
| 33 | +- `sgai.monitor.create()` → `sgai.monitor.get()` → `sgai.monitor.update()` → `sgai.monitor.delete()` — full monitor lifecycle; always delete what you create |
| 34 | +- `sgai.credits()` — check credits before and after the run |
| 35 | +- `sgai.healthy()` — health check |
| 36 | +- `sgai.history.list()` → `sgai.history.get()` — list, then fetch one entry by id |
| 37 | + |
| 38 | +For each method: capture `status`, the presence/shape of `data`, and any error. Treat a non-`success` status as a failure for that method, not for the whole run — keep going and report everything at the end. |
| 39 | + |
| 40 | +## Procedure |
| 41 | + |
| 42 | +1. Confirm the API key was provided in the user's message. If not, ask. |
| 43 | +2. Run `sgai.credits()` first so you know the starting balance and that auth works. If this 401s, stop and tell the user the key is invalid. |
| 44 | +3. Before touching the SDK, run the project's standard checks from `CLAUDE.md`: |
| 45 | + ```bash |
| 46 | + bun run format && bun run lint && bunx tsc --noEmit && bun run build && bun test |
| 47 | + ``` |
| 48 | + If any fail, report and stop — don't run live API tests against a broken build. |
| 49 | +4. Write a single throwaway script under `scripts/` (e.g. `scripts/smoke-sdk.ts`) that imports the built client and runs each method. Do not add it to the committed test suite. |
| 50 | +5. Execute it with the key passed inline. Use small inputs (short URLs, short prompts, `limit: 1` where available) to keep credit usage low. |
| 51 | +6. Clean up: delete any monitor you created, and delete the throwaway script when done. |
| 52 | +7. Report a table of `method → status → notes`, plus credits delta. |
| 53 | + |
| 54 | +## What a good report looks like |
| 55 | + |
| 56 | +``` |
| 57 | +Method Status Notes |
| 58 | +----------------------------------- |
| 59 | +healthy() ok - |
| 60 | +credits() [start] ok balance: 1234 |
| 61 | +scrape() ok got result for https://example.com |
| 62 | +extract() ok - |
| 63 | +search() ok 3 results |
| 64 | +crawl.start/get ok job <id> finished in 12s |
| 65 | +monitor lifecycle ok created/got/updated/deleted <id> |
| 66 | +history.list/get ok latest entry <id> |
| 67 | +credits() [end] ok balance: 1229 (Δ -5) |
| 68 | +``` |
| 69 | + |
| 70 | +If something fails, include the HTTP status and the first line of the error body — not the full stack, not the key. |
0 commit comments