diff --git a/versioned_docs/version-4.0.0/quickstart/cpp-mongodb-quickstart.md b/versioned_docs/version-4.0.0/quickstart/cpp-mongodb-quickstart.md new file mode 100644 index 000000000..8b613665f --- /dev/null +++ b/versioned_docs/version-4.0.0/quickstart/cpp-mongodb-quickstart.md @@ -0,0 +1,280 @@ +--- +````markdown +--- +id: samples-cpp-mongodb +title: Sample CRUD App (C++) +sidebar_label: C++ + MongoDB +description: A beginner-friendly quickstart showing how to use a C++ REST API with MongoDB and Keploy record & replay. +tags: + - cpp + - mongodb + - quickstart + - samples + - examples + - tutorial + - mongo-c-driver +keyword: + - C++ + - MongoDB + - cpp-httplib + - Keploy + - API Test generator +--- + +import Link from '@docusaurus/Link' +import InstallReminder from '@site/src/components/InstallReminder'; +import SectionDivider from '@site/src/components/SectionDivider'; +import ProductTier from '@site/src/components/ProductTier'; + + + + + +## Overview + +This quickstart shows how to run a small C++ REST API (built using `cpp-httplib`) backed by **MongoDB**, and how to use Keploy to record and replay API tests. The repo contains both Docker and non-Docker workflows so you can follow whichever matches your environment. + +--- + +## Clone the example repository + +```bash +git clone https://github.com/mishraa-G/keploy-cpp-mongodb-quickstart.git +cd keploy-cpp-mongodb-quickstart +``` + +## Prerequisites + +- A C++17 compatible compiler (gcc/clang) +- CMake +- MongoDB C Driver (libmongoc / libbson) +- Docker & docker-compose (recommended for an isolated run) + +Install helpers (examples): +````markdown +--- +id: samples-cpp-mongodb +title: Sample CRUD App (C++) +sidebar_label: C++ + MongoDB +description: A beginner-friendly quickstart showing how to use a C++ REST API with MongoDB and Keploy record & replay. +tags: + - cpp + - mongodb + - quickstart + - samples + - examples + - tutorial + - mongo-c-driver +keyword: + - C++ + - MongoDB + - cpp-httplib + - Keploy + - API Test generator +--- + +import InstallReminder from '@site/src/components/InstallReminder'; +import SectionDivider from '@site/src/components/SectionDivider'; +import ProductTier from '@site/src/components/ProductTier'; + + + + + +## Overview + +This quickstart shows how to run a small C++ REST API (built using `cpp-httplib`) backed by **MongoDB**, and how to use Keploy to record and replay API tests. The repo contains both Docker and non-Docker workflows so you can follow whichever matches your environment. + +--- + +## Clone the example repository + +```bash +git clone https://github.com/mishraa-G/keploy-cpp-mongodb-quickstart.git +cd keploy-cpp-mongodb-quickstart +``` + +## Prerequisites + +- A C++17 compatible compiler (gcc/clang) +- CMake +- MongoDB C Driver (libmongoc / libbson) +- Docker & docker-compose (recommended for an isolated run) + +Install helpers (examples): + +Linux (Ubuntu/Debian): + +```bash +sudo apt update +sudo apt install -y build-essential cmake pkg-config \ + libssl-dev libsasl2-dev libbson-dev libmongoc-dev mongodb +``` + +macOS (Homebrew): + +```bash +brew install cmake mongo-c-driver mongodb-community +``` + +> Note: Keploy's record feature relies on eBPF and currently works only on Linux (or GitHub Codespaces). If you're on macOS, use the Docker path or a Linux VM / Codespace for recording. + +--- + +## Run locally (non-Docker) + +This runs the C++ binary directly on your machine and assumes MongoDB is reachable at the configured host (see README in the repo). + +```bash +mkdir -p build +cd build +cmake .. +make -j$(nproc || echo 2) +cd .. +./build/app +``` + +You should see a log like: + +```text +Server running on port 8080 +``` + +Test the API: + +```bash +curl http://localhost:8080/health +# => {"status":"ok"} + +curl -X POST http://localhost:8080/items \ + -H "Content-Type: application/json" \ + -d '{"name":"item1"}' + +curl http://localhost:8080/items +``` + +--- + +## Run with Docker Compose (recommended) + +Docker isolates the app + MongoDB and is the easiest way to get started. From the project root: + +```bash +docker network create keploy-network || true +docker compose up --build +``` + +The app will start on port 8080 by default. Use the same curl commands above to exercise the API. + +--- + +## Record API traffic with Keploy + +Keploy's recorder uses eBPF, so recording requires Linux (or GitHub Codespaces). Install Keploy and record while bringing up the app in Docker. The compose service name in this example is `app`. + +```bash +curl --silent -O -L https://keploy.io/install.sh +source install.sh +keploy --version + +keploy record -c "docker compose up --build" \ + --container-name app \ + --buildDelay 30 +``` + +While recording, generate API traffic (examples): + +```bash +curl http://localhost:8080/health +curl -X POST http://localhost:8080/items -H "Content-Type: application/json" -d '{"name":"item1"}' +curl http://localhost:8080/items +``` + +Stop recording with Ctrl+C. Keploy will generate testcases and mock files inside the `keploy/` directory in the project. + +> Notes: +- The `docker/` or compose setup initializes the database as needed (see `docker` folder in repo). +- `docker-compose.yml` expects an external network named `keploy-network` so Keploy containers can attach to the same network for transparent recording. +- Mask secrets before committing any recordings to git. + +> If you must record on macOS, record inside a Linux VM or GitHub Codespace because eBPF is required for Keploy's recorder. This quickstart was tested in GitHub Codespaces (Linux-based). + +--- + +## Replay tests + +Replay recorded testcases against the application: + +```bash +keploy test -c "docker compose up" \ + --container-name app \ + --delay 10 \ + --buildDelay 30 +``` + +Keploy will run the recorded cases and print pass/fail results. `delay` is how long to wait for the app to become ready (in seconds). `buildDelay` is how long to wait for the image build step when using `docker compose up --build`. + +--- + +## Project structure (high level) + +``` +. +├── app/ +│ └── src/ +│ └── main.cpp +├── docker/ +│ ├── Dockerfile +│ └── docker-compose.yml +├── keploy/ +│ └── keploy.yml +└── README.md +``` + +--- + +## Troubleshooting + +- Build fails locally: ensure the MongoDB C driver headers and libs are installed and visible to CMake. +- Keploy record fails on macOS: use a Linux environment (VM, Codespaces) because eBPF is required. + +If you hit errors, open an issue in the example repo or check the repo README for environment-specific notes. + +--- + +## Quick commands cheat-sheet + +```bash +# clone +git clone https://github.com/mishraa-G/keploy-cpp-mongodb-quickstart.git + +# local build & run +mkdir build && cd build && cmake .. && make -j$(nproc || echo 2) +cd .. && ./build/app + +# docker +docker network create keploy-network || true +docker compose up --build + +# record (Docker) +keploy record -c "docker compose up --build" --container-name app --buildDelay 30 + +# replay +keploy test -c "docker compose up" --container-name app --delay 10 --buildDelay 30 +``` + +--- + +## Wrapping up 🎉 + +You’ve successfully: + +- Built a C++ REST API with MongoDB +- Recorded API traffic using Keploy +- Replayed tests automatically without writing test code + +Explore `keploy/` to see generated YAMLs, mocks, and testcases. Tweak them and re-run `keploy test` to validate changes. + +Happy testing! 🚀 + +```` \ No newline at end of file diff --git a/versioned_docs/version-4.0.0/quickstart/php-postgressql-quickstart.md b/versioned_docs/version-4.0.0/quickstart/php-postgressql-quickstart.md new file mode 100644 index 000000000..f711cdea3 --- /dev/null +++ b/versioned_docs/version-4.0.0/quickstart/php-postgressql-quickstart.md @@ -0,0 +1,163 @@ +--- +id: samples-php-postgres-quickstart +title: PHP + PostgreSQL (Quick Starter) +sidebar_label: PHP + PostgreSQL (Quick Starter) +description: Quick starter for the keploy-php-postgres-quickstart example repository +tags: + - php + - postgresql + - quickstart +--- + +# PHP + PostgreSQL — Quick Starter + +import InstallReminder from '@site/src/components/InstallReminder'; +import SectionDivider from '@site/src/components/SectionDivider'; + + + +This short quick starter gets you up and running with the example repo: + +https://github.com/mishraa-G/keploy-php-postgres-quickstart + +It covers cloning, running with Docker (recommended), recording API traffic with Keploy (Linux), and replaying tests. The example uses PHP (Apache) + PostgreSQL and provides a `docker-compose.yml` and `keploy.yml` for end-to-end recording. + +## 1) Clone the repo + +```bash +git clone https://github.com/mishraa-G/keploy-php-postgres-quickstart.git +cd keploy-php-postgres-quickstart +``` + +## 2) Run with Docker Compose (recommended) + +Most example repos provide a `docker-compose.yml` that brings up the app and PostgreSQL. From the project root: + +```bash +docker network create keploy-network || true +docker compose up --build +``` + +The example app is served under `/index.php` and the service listens on port 8080. Verify the health endpoint: + +```bash +curl http://localhost:8080/index.php/health +# -> {"status":"ok"} +``` + +The repository exposes these REST endpoints (from the example): + +- GET /index.php/health +- POST /index.php/users +- GET /index.php/users +- GET /index.php/users/{id} +- DELETE /index.php/users/{id} + +Example requests: + +```bash +# create user +curl -X POST http://localhost:8080/index.php/users \ + -H 'Content-Type: application/json' \ + -d '{"name":"Alice","email":"alice@example.com"}' + +# list users +curl http://localhost:8080/index.php/users +``` + +## 3) Run locally without Docker (optional) + +If you want to run PHP & Postgres locally, install PHP >= 8.0 with `pgsql`/`pdo_pgsql` enabled and a local PostgreSQL instance. Follow the repo README for exact composer commands (if used) and DB configuration. Typical local flow: + +```bash +# install PHP deps (if composer is used) +composer install + +# configure DB connection (env file or config) +# start PHP built-in server (example) +php -S 0.0.0.0:8080 -t public +``` + +Refer to the repo README for exact config keys and any environment variables. + +## 4) Record API traffic with Keploy (Linux only) + +Keploy's recorder uses eBPF, so recording requires Linux (or GitHub Codespaces). Install Keploy and record while bringing up the app in Docker. The compose service name in this example is `app`. + +```bash +curl --silent -O -L https://keploy.io/install.sh +source install.sh +keploy --version + +keploy record -c "docker compose up --build" \ + --container-name app \ + --buildDelay 30 +``` + +While recording, run the example curl commands above (or use Postman) to generate traffic. Stop recording with Ctrl+C. Keploy will create a `keploy/` directory containing recorded tests, mock files, and test-sets. + +> Notes: +- The `db` service initializes the `users` table using `app/migrate.sql` (see repo). +- `docker-compose.yml` expects an external network named `keploy-network` so Keploy containers can attach to the same network for transparent recording. +- Mask secrets before committing any recordings to git. + +> If you're on macOS, run the recorder inside a Linux VM or Codespace because eBPF is required. This quickstart was tested in GitHub Codespaces (Linux-based). + +## 5) Replay recorded tests + +Replay recorded testcases against the application: + +```bash +keploy test -c "docker compose up" \ + --container-name app \ + --delay 10 \ + --buildDelay 30 +``` + +Keploy will run the recorded cases and print pass/fail results. `delay` is how long to wait for the app to become ready (in seconds). `buildDelay` is how long to wait for the image build step when using `docker compose up --build`. + +## Project structure (high level) + +``` +. +├── app/ +│ ├── index.php +│ ├── db.php +│ └── migrate.sql +├── Dockerfile +├── docker-compose.yml +├── keploy.yml +└── README.md +``` + +## Troubleshooting + +- If the app doesn't start, check container logs with `docker compose logs --follow` and confirm ports. +- Local run/build issues: ensure PHP extensions (`pgsql`/`pdo_pgsql`) and composer deps are installed per the project's README. +- Keploy recording fails on macOS: use Linux VM / GitHub Codespace for recording. + +## Quick cheat-sheet + +```bash +# clone +git clone https://github.com/mishraa-G/keploy-php-postgres-quickstart.git + +# docker run (recommended) +docker network create keploy-network || true +docker compose up --build + +# record (Linux only) +keploy record -c "docker compose up --build" --container-name app --buildDelay 30 + +# replay +keploy test -c "docker compose up" --container-name app --delay 10 --buildDelay 30 +``` + +--- + +If you'd like, I can: + +- Add this quick-starter to the top-level `docs/quickstart/` folder so it's available in the main docs site +- Add a short `devcontainer` snippet (Codespaces) that pre-installs the Keploy CLI and helper scripts (`scripts/record.sh`, `scripts/replay.sh`) as suggested in the upstream README + +Which would you like next?