api-endpoint-tester

5 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

• skills/api-endpoint-tester/SKILL.md1.8 KBe00113fedcefupstream ↗

  ---
  name: api-endpoint-tester
  description: Runs a list of HTTP checks against a base URL from a JSON file and reports status codes, response time and body assertions. Use when the user asks whether an API is up, wants a smoke test after a deploy, or needs to verify that endpoints return what the docs promise.
  license: MIT
  metadata:
    version: 1.0.0
    author: Lethe044
    tags: [api, http, testing, smoke-test]
  ---
  
  # API endpoint tester
  
  A tiny smoke test runner with no dependencies. It sends real HTTP requests, so only point it at services
  the user owns or has permission to test.
  
  ## When to use
  
  - After a deploy, to confirm the main endpoints respond.
  - When the user suspects an endpoint changed shape or status code.
  - To turn a list of curl commands into a repeatable check.
  
  ## How to run
  
  ```bash
  python scripts/check_api.py checks.json --base-url https://staging.example.com
  ```
  
  The checks file is a JSON list:
  
  ```json
  [
    {"name": "health", "method": "GET", "path": "/health", "expect_status": 200, "expect_body_contains": "ok"},
    {"name": "create", "method": "POST", "path": "/items", "json": {"name": "demo"}, "expect_status": 201}
  ]
  ```
  
  Optional fields: `headers` (object), `json` (request body), `expect_status` (default 200),
  `expect_body_contains` (string) and `timeout` (seconds, default 10).
  
  ## Output
  
  JSON with `base_url`, `passed`, `failed` and `results`. Each result has `name`, `ok`, `status`,
  `elapsed_ms` and, when it failed, a `reason`. The exit code is 1 when any check fails.
  
  ## After running
  
  Report failures first with the reason and status code. Mention slow endpoints (over one second). Do not retry
  failing POST requests automatically, they may create duplicates.
  
  ## Errors
  
  A missing checks file exits with code 2. Invalid JSON or a malformed check exits with code 3.
  Connection errors are reported as failed checks, not crashes.
  

• skills/api-endpoint-tester/scripts/check_api.py2.8 KB0345486871c7upstream ↗

  #!/usr/bin/env python3
  """Run HTTP checks from a JSON file and report the results."""
  import argparse
  import json
  import sys
  import time
  import urllib.error
  import urllib.request
  
  
  def run_check(base_url, check):
      method = str(check.get("method", "GET")).upper()
      url = base_url.rstrip("/") + "/" + str(check.get("path", "")).lstrip("/")
      headers = dict(check.get("headers") or {})
      data = None
      if "json" in check:
          data = json.dumps(check["json"]).encode("utf-8")
          headers.setdefault("Content-Type", "application/json")
      request = urllib.request.Request(url, data=data, headers=headers, method=method)
      started = time.time()
      status, body, reason = None, "", ""
      try:
          with urllib.request.urlopen(request, timeout=float(check.get("timeout", 10))) as resp:
              status = resp.status
              body = resp.read(200000).decode("utf-8", errors="replace")
      except urllib.error.HTTPError as exc:
          status = exc.code
          body = exc.read(200000).decode("utf-8", errors="replace")
      except (urllib.error.URLError, OSError) as exc:
          reason = "request failed: %s" % getattr(exc, "reason", exc)
      elapsed = int((time.time() - started) * 1000)
      if not reason:
          expected = int(check.get("expect_status", 200))
          if status != expected:
              reason = "expected status %d, got %d" % (expected, status)
          elif "expect_body_contains" in check and str(check["expect_body_contains"]) not in body:
              reason = "body does not contain %r" % check["expect_body_contains"]
      result = {"name": check.get("name") or "%s %s" % (method, check.get("path", "")), "ok": not reason,
                "status": status, "elapsed_ms": elapsed}
      if reason:
          result["reason"] = reason
      return result
  
  
  def main(argv=None):
      parser = argparse.ArgumentParser(description=__doc__)
      parser.add_argument("checks", help="JSON file with a list of checks")
      parser.add_argument("--base-url", required=True)
      args = parser.parse_args(argv)
      try:
          with open(args.checks, encoding="utf-8") as fh:
              checks = json.load(fh)
      except OSError:
          print("file not found: %s" % args.checks, file=sys.stderr)
          return 2
      except ValueError:
          print("invalid JSON in %s" % args.checks, file=sys.stderr)
          return 3
      if not isinstance(checks, list) or not all(isinstance(c, dict) and "path" in c for c in checks):
          print("checks must be a list of objects that each have a path", file=sys.stderr)
          return 3
      results = [run_check(args.base_url, c) for c in checks]
      failed = sum(1 for r in results if not r["ok"])
      print(json.dumps({"base_url": args.base_url, "passed": len(results) - failed, "failed": failed,
                        "results": results}))
      return 1 if failed else 0
  
  
  if __name__ == "__main__":
      sys.exit(main())
  

• skills/api-endpoint-tester/tests/cases.json423 B72e574414de9upstream ↗

  {
    "entry": "scripts/check_api.py",
    "cases": [
      {"name": "missing checks file", "kind": "error", "args": ["nope.json", "--base-url", "http://127.0.0.1:1"],
       "expect_exit": 2, "stderr_contains": "file not found"},
      {"name": "invalid json", "kind": "error", "args": ["bad.json", "--base-url", "http://127.0.0.1:1"],
       "files": {"bad.json": "{oops"}, "expect_exit": 3, "stderr_contains": "invalid JSON"}
    ]
  }
  

• skills/api-endpoint-tester/tests/test_check_api.py3.1 KBb73e8ee6750aupstream ↗

  import json
  import os
  import subprocess
  import sys
  import tempfile
  import threading
  import unittest
  from http.server import BaseHTTPRequestHandler, HTTPServer
  
  SCRIPT = os.path.join(os.path.dirname(__file__), "..", "scripts", "check_api.py")
  
  
  class Handler(BaseHTTPRequestHandler):
      def log_message(self, *args):
          return
  
      def _reply(self, code, body):
          data = body.encode()
          self.send_response(code)
          self.send_header("Content-Length", str(len(data)))
          self.end_headers()
          self.wfile.write(data)
  
      def do_GET(self):
          if self.path == "/health":
              self._reply(200, "status ok")
          else:
              self._reply(404, "missing")
  
      def do_POST(self):
          length = int(self.headers.get("Content-Length", 0))
          payload = json.loads(self.rfile.read(length) or b"{}")
          self._reply(201, "created " + payload.get("name", ""))
  
  
  class CheckApiTests(unittest.TestCase):
      @classmethod
      def setUpClass(cls):
          cls.server = HTTPServer(("127.0.0.1", 0), Handler)
          cls.url = "http://127.0.0.1:%d" % cls.server.server_address[1]
          threading.Thread(target=cls.server.serve_forever, daemon=True).start()
  
      @classmethod
      def tearDownClass(cls):
          cls.server.shutdown()
          cls.server.server_close()
  
      def run_script(self, checks, base=None):
          with tempfile.NamedTemporaryFile("w", suffix=".json", delete=False) as fh:
              json.dump(checks, fh)
          try:
              proc = subprocess.run([sys.executable, SCRIPT, fh.name, "--base-url", base or self.url],
                                    capture_output=True, text=True, timeout=30)
          finally:
              os.unlink(fh.name)
          return proc
  
      def test_passing_checks(self):
          proc = self.run_script([
              {"name": "health", "path": "/health", "expect_body_contains": "ok"},
              {"name": "create", "method": "POST", "path": "/items", "json": {"name": "demo"}, "expect_status": 201,
               "expect_body_contains": "demo"}])
          self.assertEqual(proc.returncode, 0, proc.stderr)
          data = json.loads(proc.stdout)
          self.assertEqual((data["passed"], data["failed"]), (2, 0))
  
      def test_wrong_status_fails(self):
          proc = self.run_script([{"name": "gone", "path": "/nope"}])
          self.assertEqual(proc.returncode, 1)
          result = json.loads(proc.stdout)["results"][0]
          self.assertFalse(result["ok"])
          self.assertIn("expected status 200, got 404", result["reason"])
  
      def test_body_assertion_fails(self):
          proc = self.run_script([{"path": "/health", "expect_body_contains": "degraded"}])
          self.assertEqual(proc.returncode, 1)
  
      def test_connection_error_is_a_failed_check(self):
          proc = self.run_script([{"path": "/health", "timeout": 2}], base="http://127.0.0.1:1")
          self.assertEqual(proc.returncode, 1)
          self.assertIn("request failed", json.loads(proc.stdout)["results"][0]["reason"])
  
      def test_bad_checks_file(self):
          proc = self.run_script({"not": "a list"})
          self.assertEqual(proc.returncode, 3)
  
  
  if __name__ == "__main__":
      unittest.main()
  

• README.mdupstream ↗

  Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/lethe044-agentskill-kit-skills-api-endpoint-tester.md