Skip to content

docs: fix deviations found while walking through the quickstart guides - #981

Open
Namanv0509 wants to merge 9 commits into
keploy:mainfrom
Namanv0509:docs/quickstart-deviations-fixes
Open

Namanv0509 wants to merge 9 commits into
keploy:mainfrom
Namanv0509:docs/quickstart-deviations-fixes

Conversation

@Namanv0509

@Namanv0509 Namanv0509 commented Nov 18, 2026 •

Copy link
Copy Markdown

What has changed?

I ran each quickstart end to end and fixed every place the docs didn't match what actually happens. The changes touch 17 files under versioned_docs/version-4.0.0/quickstart/.

Missing setup steps

  • Added docker network create keploy-network where the sample's compose file needs that external network: go-mux-mysql, go-mux-sql, java-spring-postgres, node-jwt-sql, python-django-sql and samples-java.
  • Added a note to change localhost to the container or service name where the app runs in Docker: go-gin-redis (myredis), go-mux-sql (postgres) and python-fastapi-sql (postgres).
  • Added the dotnet-ef tool install to the csharp-dotnet-postgres prerequisites.
  • Added the macOS port 5000 / AirPlay Receiver conflict note to flask-redis.
  • Added a Python 3.11 requirement to python-fastapi-twilio. Newer versions such as 3.13 can't build some pinned dependencies.

Wrong commands and flags

  • Changed --containerName and --buildDelay to --container-name and --build-delay.
  • Removed sudo from docker compose commands.
  • Changed ts-node to npx ts-node in sample-ts.
  • Replaced <networkName> with the real network name gin-redis_default.
  • Added a trailing slash to the Django /user/<USER_ID>/ URLs.
  • Fixed cd spring-boot-xml/... to cd samples-java/spring-boot-xml/....
  • Fixed the escaped quotes in a curl command.

Wrong or outdated content

  • Fixed copy-paste errors: "mongoDB" to PostgreSQL, "Mongo" to Redis, and "express-mongo folder" to node-jwt.
  • Fixed testcases/ to keploy/, and Keploy/reports to keploy/reports.
  • Corrected the expected test counts and removed stale coverage lines in express-postgresql-prisma.
  • Corrected the JWT expiry to 35 seconds in node-jwt-sql.
  • Corrected the main.go host and line number (postgresDb, line 47) in samples-echo.
  • Refreshed the python-fastapi-sql sample output with a real recording: keploy/test-set-0/tests/, mocks.yaml, and current test and mock formats.
  • Removed trailing commas that made the JSON invalid in python-fastapi-twilio.
  • Moved the "Clone the Sample App" section ahead of its first use in python-fastapi-twilio.

Added clarifications

  • docker compose up stays in the foreground, so run it in its own terminal.
  • Stop the app or recording with Ctrl+C before the next step.
  • The "could not read mocks.yaml" warning is expected for apps with no external dependencies (java-spring-boot-xml).
  • The database starts empty, so add data before expecting results (java-spring-postgres).

Type of change

  • Documentation update (if none of the other choices apply).

How Has This Been Tested?

  • Walked through each quickstart with the commands as written, and fixed the places where they failed or the output differed.
  • Successfully ran build

Checklist:

  • My code follows the style guidelines of this project.
  • I have performed a self-review of my own code.

Signed-off-by: Namanv0509 <namanverma00260@gmail.com>

@dhananjay6561 dhananjay6561 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hey naman, thanks for this, walking through every quickstart end to end is exactly the kind of grind nobody wants to do and it shows 🙌

i went through each change and checked it against the sample repos and the keploy source. most of it is spot on: the external network steps, the localhost to service name notes, npx ts-node, the django trailing slash (put without it actually 500s on APPEND_SLASH), the twilio json commas, the jwt 35s expiry, the prisma test count, and the fastapi-sql yaml refresh all check out.

left comments inline on the spots that still need a bit of work. the main ones are a few flows that still fail as written (django can't reach postgres, csharp is cd'ing into the wrong folder, and fastapi-sql / flask-redis / sample-ts / twilio need the same docker network create you added elsewhere). the rest are small.

couple of general things:

  • --containerName / --buildDelay still work since the cli keeps camelCase aliases, so this is more about consistency than a broken flag, which is totally fine. heads up that python-flask-mongo.md in the same folder still uses the old ones if you want to catch it here, otherwise it's fine as a follow up
  • django-sql and fastapi-twilio still say test-1.yml / mocks.yml in places, keploy writes .yaml now. optional
  • the pr description still has the template line "This PR Resolves #(issue number, or delete this line if there is none)", you can drop it

ping me if anything's unclear, happy to pair on the django one

```

#### First things first, update the postgres host on line 41 in main.go to postgres from localhost.
#### First things first, check the postgres host on line 47 in main.go. It is already set to `postgresDb`, the Postgres service name in `docker-compose.yml`, so no change is needed for Docker.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

small thing: in the echo-sql compose file the service is actually called postgres. postgresDb is the container_name (and the network alias), so maybe just say that:

Suggested change
#### First things first, check the postgres host on line 47 in main.go. It is already set to `postgresDb`, the Postgres service name in `docker-compose.yml`, so no change is needed for Docker.
#### First things first, check the postgres host on line 47 in main.go. It is already set to `postgresDb`, the container name (and network alias) of Postgres in `docker-compose.yml`, so no change is needed for Docker.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch, reworded to say it's the container name and network alias. Fixed.

curl http://localhost:8082/GuwHCgoQ
```

`GuwHCgoQ` is just an example short code; use the one returned in the `url` field of your own response.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nice addition 👍 the local section further down (around line 213 to 223) uses Lhr4BWAi the same way, might be worth dropping the same one liner there too

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, added the same one-liner to the local section too.

```

> **Since we are using docker to run the application, we need to update the `postgres` host on line 41 in `main.go`, update the host to `localhost`.**
> **Since we are using docker to run the application, we need to update the `postgresDb` host on line 47 in `main.go`, update the host to `localhost`.**

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

line number and host are right now, but this is the "running app locally" section, so the "since we are using docker" bit reads backwards. main.go:48 even has the comment // host: "localhost" when using natively

Suggested change
> **Since we are using docker to run the application, we need to update the `postgresDb` host on line 47 in `main.go`, update the host to `localhost`.**
> **Since we are running the application natively, update the `postgresDb` host on line 47 in `main.go` to `localhost`.**

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep, that read backwards. Switched it to "running natively" as suggested.

docker run -p 3306:3306 --rm --name mysql --network keploy-network -e MYSQL_ROOT_PASSWORD=my-secret-pw -d mysql:latest
```

MySQL can take a while to start on its first run. Wait until `docker logs mysql` shows `ready for connections` before moving on.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

good call adding this, the app only pings mysql once and exits if it fails. one gotcha though: on first run the mysql image starts a temporary server during init and that one also logs ready for connections (with port: 0), so people can jump in too early. the sample's own readme says to wait for Stopping temporary server. maybe:

Suggested change
MySQL can take a while to start on its first run. Wait until `docker logs mysql` shows `ready for connections` before moving on.
MySQL can take a while to start on its first run. Wait until `docker logs mysql` shows `ready for connections` with `port: 3306` (the earlier `port: 0` line is MySQL's temporary init server) before moving on.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice, the temporary init server thing is a real trap. Added the port: 3306 wording.


### Lights, Camera, Record! 🎥

The `docker-compose.yml` attaches both services to an external `keploy-network`, so create it once:

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is right for the docker flow 👍 the local section uses the same compose file though (docker compose up postgres around line 283), so someone who skips straight to running locally will hit the same "network keploy-network declared as external, but could not be found" error. worth adding the network create there as well.

also while you're in there, line 276 still says the host is on line 10 of main.go, it's on line 18 now

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed both: added the network create to the local section and corrected the line number to 18.

```

Note: If you face any issues while setting up the database, please try running docker compose up again. The issue should not occur the second time.
Note: `docker compose up` keeps running in the foreground, so run it in its own terminal (or add `-d`) and continue the next steps in another one. If the first run fails while the database is being initialised (for example with `ERROR 1064` from MariaDB), run `docker compose up` again. The issue should not occur the second time.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

tiny one: the db image is built from Dockerfile-ohdb which is FROM mysql:8.0, only the env var names say mariadb

Suggested change
Note: `docker compose up` keeps running in the foreground, so run it in its own terminal (or add `-d`) and continue the next steps in another one. If the first run fails while the database is being initialised (for example with `ERROR 1064` from MariaDB), run `docker compose up` again. The issue should not occur the second time.
Note: `docker compose up` keeps running in the foreground, so run it in its own terminal (or add `-d`) and continue the next steps in another one. If the first run fails while the database is being initialised (for example with `ERROR 1064` from MySQL), run `docker compose up` again. The issue should not occur the second time.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated, it says MySQL now.

Review generated test reports in `keploy/reports`.

:::note
You may see a warning such as `Could not read the mock file ... mocks.yaml: no such file`. This is expected here: the app has no external dependencies, so no mocks are recorded.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the explanation is right, this app makes no outbound calls so there's nothing to mock. but i couldn't find this exact warning text anywhere in the keploy source, and on replay a missing mocks file is just skipped quietly (pkg/platform/yaml/mockdb/db.go). which keploy version were you on? if you still have the log line, paste it here. otherwise maybe word it without quoting a message:

Suggested change
You may see a warning such as `Could not read the mock file ... mocks.yaml: no such file`. This is expected here: the app has no external dependencies, so no mocks are recorded.
No `mocks.yaml` is created for this sample: the app makes no outbound calls (no database or external API), so there is nothing to mock. That is expected.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fair, I couldn't back up the exact warning text, so I used your wording without quoting a message.

<img src="https://keploy-devrel.s3.us-west-2.amazonaws.com/docs/webp-s3/img/pet-record.webp" alt="Sample Keploy Test Result Node JWT" width="100%" style={{ borderRadius: '5px' }} />

Now you can start interacting with the UI and Keploy will automatically create the testcases and mocks for it in a folder named 'keploy'.
Now you can start interacting with the UI and Keploy will automatically create the testcases and mocks for it in a folder named 'keploy'. The database starts empty, so begin by adding a few owners and pets from the UI; the lists stay empty until you do.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the "starts empty" part is right (ddl-auto=create and populateDB.sql is commented out). one catch: adding a pet needs a pet type, and the type dropdown is required and filled from /pettypes, which is also empty. so people will get stuck at the pet form. maybe say "create a pet type under Pet Types first, then add an owner and a pet". same for line 207

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated both spots to say create a pet type first, then an owner and a pet.

This is a summary of the test cases recorded
<img src="https://keploy-devrel.s3.us-west-2.amazonaws.com/docs/webp-s3/img/keploy-testcase-employee.webp" alt="Sample Keploy Test Summary Java" width="100%" style={{ borderRadius: '5px' }} />

Unlike the binary steps above, no extra noise configuration is needed for this Docker run; the `body.timestamp` noise step applies only to the binary instructions.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

did this actually pass for you in docker without the noise? asking because EmployeeController.java:39 sets timestamp from Instant.now() on every POST, and the Dockerfile runs the same jar, so i'd expect the same diff in both modes. if it really did pass i'm curious what made the difference. otherwise i'd point people to the same noise step instead

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You're right, the timestamp changes in Docker too. Removed that claim and pointed to the same noise step.

### Prerequisites

- Install the [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0).
- Install the EF Core tool, using version 8 to match the project (the latest `dotnet-ef` does not work with the .NET 8 SDK):

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

good catch on pinning dotnet-ef to 8, the latest one doesn't run on .NET 8. two things nearby that'll still break this flow though:

  1. line 72 does cd samples-csharp, but the project and compose file moved to crud-app/ (samples-csharp a192656). from the repo root docker-compose up and both dotnet ef commands fail. should be cd samples-csharp/crud-app
  2. crud-app/Migrations/ already has InitialMigration committed, so dotnet ef migrations add InitialMigration (around line 98) errors out with a duplicate name. i think only dotnet ef database update is needed

optional: after a global tool install people often need export PATH="$PATH:$HOME/.dotnet/tools", the sample readme mentions it

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed all three: cd samples-csharp/crud-app, dropped migrations add since InitialMigration is already committed, and added the PATH export.

Signed-off-by: Namanv0509 <namanverma00260@gmail.com>

@dhananjay6561 dhananjay6561 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thanks for turning the last round around so quickly naman, every point from before is addressed and i re-checked them against the sample repos 🙌

this round is small. the one thing blocking merge is the prettier check, it fails on python-fastapi-sql.md only (details inline). the other comments are clarity tweaks.

optional, if you're up for it while you're in this file: the "Running App Locally on Linux/WSL" section of python-fastapi-sql.md never starts Postgres. it goes from the clone straight to keploy record -c "uvicorn ...", but application/database.py connects to localhost:5432/studentdb, so there's nothing for it to connect to. a "start Postgres" step like the other quickstarts have would close that gap. totally fine as a follow up too.

also the PR description still has the template line "This PR Resolves #(issue number, or delete this line if there is none)", you can drop it.

url: http://127.0.0.1:8000/students/
header:
Accept: "*/*"
Accept: '*/*'

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this file is why the prettier check is red (run). prettier 2.8.8 (the version CI pins) wants two changes in the refreshed yaml, in both the docker and the local section:

  1. double quotes here (and on line 375)
  2. 2-space indentation instead of 4 inside the mocks.yaml block (lines 197-260 and 413-476)

easiest is to let it rewrite the file: npx prettier@2.8.8 --write versioned_docs/version-4.0.0/quickstart/python-fastapi-sql.md. i ran that locally and it only touches those lines, the yaml stays the same data.

Suggested change
Accept: '*/*'
Accept: "*/*"

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ran prettier 2.8.8 on the file, it passes now. Thanks for the exact command.

--header 'x-access-token: <TOKEN>'
```

Replace `<TOKEN>` with the `accessToken` returned by the sign-in response in step 3.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nice addition. since you also fixed the expiry to 35 seconds, it'd help to warn people here. auth.controller.js signs the token with expiresIn: 35 (L71) and authJwt.js returns 401 Unauthorized! once it's expired (L23). anyone who takes more than 35s to copy the token from step 3 will record a 401 here instead of User Content.

Suggested change
Replace `<TOKEN>` with the `accessToken` returned by the sign-in response in step 3.
Replace `<TOKEN>` with the `accessToken` returned by the sign-in response in step 3. The token expires 35 seconds after sign-in, so send this request within that window (or sign in again first), otherwise the app answers `401` with `Unauthorized!`.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added the 35s warning to the local section.

--header 'x-access-token: <TOKEN>'
```

Replace `<TOKEN>` with the `accessToken` returned by the sign-in response in step 3.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same as the local section, the docker flow has the same 35s window:

Suggested change
Replace `<TOKEN>` with the `accessToken` returned by the sign-in response in step 3.
Replace `<TOKEN>` with the `accessToken` returned by the sign-in response in step 3. The token expires 35 seconds after sign-in, so send this request within that window (or sign in again first), otherwise the app answers `401` with `Unauthorized!`.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same warning added to the docker section.

This is a summary of the test cases recorded
<img src="https://keploy-devrel.s3.us-west-2.amazonaws.com/docs/webp-s3/img/keploy-testcase-employee.webp" alt="Sample Keploy Test Summary Java" width="100%" style={{ borderRadius: '5px' }} />

The `timestamp` field changes on every run here as well, so add `body.timestamp` to the noise in `keploy.yml`, as in the noise step above, before running the tests.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thanks for fixing this. two small follow ups:

  1. line 305 in this docker section (and line 150 in the binary one) still says "The timestamp would automatically be ignored during testing because it'll always be different." that now contradicts this note and the failing diff shown in the binary section. EmployeeController.java sets timestamp from Instant.now() on every create (L39), so i'd drop that sentence in both places, like you did in go-mux-mysql.
  2. the note says "before running the tests" but it sits after the keploy test command and its output. moving it above the command (around line 335) would match what it asks people to do.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On this one I checked with a fresh Docker run on Keploy 3.9.3: it adds body.timestamp as noise on its own when recording stops, and keploy test passed 2/2 without touching keploy.yml. So I reverted my note and kept the original "timestamp is ignored automatically" wording in the docs.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

checked this in the enterprise source and you are right, thanks for pushing back with an actual run. keploy record runs an auto-replay by default once you stop it, and that pass writes response diffs like body.timestamp into the test file as noise (record_auto_replay.go and sandbox_auto_noise_hooks.go in enterprise). so "ignored automatically" holds.

one follow-up that falls out of this: the binary section of this same file still shows a failing timestamp diff (around lines 192 to 242) and then says to add body.timestamp to noise in keploy.yml. with auto-replay that only happens if someone skips it with a second Ctrl+C. could you either reframe that block as the "if you skipped the auto-replay" case, or drop it, so both sections tell the same story?

Comment on lines +280 to +282
Let's breathe life into your Postgres container. A simple spell should do the trick:

The `docker-compose.yml` attaches the services to an external `keploy-network`, so create it once:

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

small readability thing: "A simple spell should do the trick:" is now followed by another sentence instead of the command. merging the two keeps the flow:

Suggested change
Let's breathe life into your Postgres container. A simple spell should do the trick:
The `docker-compose.yml` attaches the services to an external `keploy-network`, so create it once:
Let's breathe life into your Postgres container. The `docker-compose.yml` attaches the services to an external `keploy-network`, so create it once and then start Postgres:

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Merged the two sentences, reads better now.

@dhananjay6561

Copy link
Copy Markdown
Member

@Namanv0509 a few lines in this PR can only be confirmed by actually running the samples, so could you re-run these once and confirm each one here (a screenshot or the log line is enough)?

  1. java-spring-boot-openhospital.md: "The database and the UI do not need to be running for keploy test, as Keploy replays the recorded mocks." Stop the DB and UI containers, run keploy test, and check that the tests still pass.
  2. java-spring-boot-openhospital.md: the first-run ERROR 1064 from MySQL. Does it really show up on a fresh run (with the volume removed), and does a second docker compose up really fix it?
  3. go-mux-mysql.md: the port: 0 line from MySQL's temporary init server, followed by ready for connections with port: 3306. Please paste the actual docker logs mysql lines so the wording in the doc matches them.
  4. flask-redis.md: the AirPlay Receiver note on macOS. Is the error text exactly address already in use, and is the settings path (System Settings → General → AirDrop & Handoff → AirPlay Receiver) right on your macOS version?

If anything doesn't match, update the text to what you actually see. If you can't reproduce something, it's better to drop that line than to keep it. Thanks!

Signed-off-by: Namanv0509 <namanverma00260@gmail.com>

@Namanv0509 Namanv0509 left a comment

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the thorough re-check. Everything is pushed: prettier is fixed on python-fastapi-sql, the 35s token warning is in both node-jwt sections, go-mux-sql reads cleanly, and I added the Postgres start step to the local section of python-fastapi-sql (with the network create). For samples-java I kept the original wording, since Keploy 3.9.3 marks the timestamp as noise on its own. Details are in the inline replies.

@Namanv0509

Copy link
Copy Markdown
Author
  1. Confirmed. I recorded the API, removed the DB container and ran keploy test . 5/5 passed.
  2. Confirmed. On a fresh DB the first docker compose up fails with ERROR 1064 near --- MEDICALDSRINVENTORY -- and exits with code 1. The second docker compose up starts normally.
  3. Confirmed. The logs show ready for connections ... port: 0, then Stopping temporary server, then ready for connections ... port: 3306. The doc wording matches.
  4. I ran the quickstart end to end on port 5000 without any changes. Record and keploy test passed 5/5. When AirPlay Receiver is on, it does hold port 5000 here (bind: address already in use). The Settings path is System Settings → General → AirDrop & Continuity → AirPlay Receiver.

@dhananjay6561 dhananjay6561 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thanks naman, the round 2 fixes are in and CI is green (prettier included). and good call pushing back on the samples-java timestamp with a real run, i checked the enterprise source and you're right (details in that thread).

that finding has a knock-on effect though: since keploy record now marks changing fields as noise by itself, the new OTP note in go-gin-redis and the binary section of samples-java both describe a failure most people won't hit anymore. comments inline, plus three small things (one suggestion from last round that didn't land, the macOS settings name, and a missing pip install in fastapi-sql's local section).

optional, while you're in these files: java-spring-postgres.md (line 222) and samples-java.md (line 346) still explain the flag as buildDelay right under commands that now use --build-delay.

Time to put things to the test 🧪

:::note
The OTP changes on every request, so mark it as noise before replaying. Add `body.otp` under `assertions.noise` in the recorded OTP test (the `GET` test in `keploy/test-set-0/tests/`).

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

did you actually need this on 3.9.3? asking because of what you found in samples-java. when you stop keploy record, it runs an auto-replay by default ("auto-replay: recording stopped ... now replaying what was just recorded to check for noise") and writes any response-body diff it sees into the test file as noise (sandbox_auto_noise_hooks.go in enterprise). that same pass should mark body.otp on its own, the same way it marked body.timestamp for you there. the example test yaml right above (line 180) also already shows body.otp under noise, so the note reads a bit like a step that's already done.

if the GET test really did fail on otp for you, could you paste the diff? in that case two more things:

  • the POST /api/verifyCode response has a token that changes on every run too (helpers/token/token.go:22 sets exp from time.Now()), so it would need the same treatment
  • keploy now writes noise as a map, so the snippet should look like this:
assertions:
  noise:
    body.otp: []

if not, i'd reword it for the case where it's actually needed, which is when someone skips the auto-replay with a second Ctrl+C:

Suggested change
The OTP changes on every request, so mark it as noise before replaying. Add `body.otp` under `assertions.noise` in the recorded OTP test (the `GET` test in `keploy/test-set-0/tests/`).
If you skipped Keploy's automatic noise check by pressing `Ctrl+C` a second time when stopping the recording, the OTP will show up as a diff, since it changes on every request. Mark it as noise by adding `body.otp: []` under `assertions.noise` in the recorded `GET` test in `keploy/test-set-0/tests/`.

same note at line 471 in the local section.

Comment on lines 280 to +282
Let's breathe life into your Postgres container. A simple spell should do the trick:

The `docker-compose.yml` attaches the services to an external `keploy-network`, so create it once.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

looks like this one didn't land: "A simple spell should do the trick:" still ends in a colon and is followed by another sentence instead of the command. merging the two:

Suggested change
Let's breathe life into your Postgres container. A simple spell should do the trick:
The `docker-compose.yml` attaches the services to an external `keploy-network`, so create it once.
Let's breathe life into your Postgres container. The `docker-compose.yml` attaches the services to an external `keploy-network`, so create it once and then start Postgres:

### Lights, Camera, Record! 🎥

:::note macOS
Port `5000` is used by the AirPlay Receiver on macOS, so the app fails to start with `address already in use`. Turn it off under **System Settings → General → AirDrop & Continuity → AirPlay Receiver** before recording.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

checked this on macOS 26: the pane really is called AirDrop & Continuity there, so your fix is right. on macOS 13 to 15 it's still AirDrop & Handoff though, and a lot of people are still on those. maybe name both:

Suggested change
Port `5000` is used by the AirPlay Receiver on macOS, so the app fails to start with `address already in use`. Turn it off under **System Settings → General → AirDrop & Continuity → AirPlay Receiver** before recording.
Port `5000` is used by the AirPlay Receiver on macOS, so the app fails to start with `address already in use`. Turn it off under **System Settings → General → AirDrop & Continuity → AirPlay Receiver** (called **AirDrop & Handoff** on macOS 15 and earlier) before recording.

```bash
docker network create keploy-network
docker compose up -d postgres
```

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thanks for adding this 👍 one more step this section still skips: nothing installs the python deps, so uvicorn won't exist when keploy record runs. the sample's README does pip3 install -r requirements.txt, which pulls in uvicorn, fastapi, psycopg2-binary and SQLAlchemy. something like this after starting Postgres:

python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt

also a small gotcha: the docker section asks people to change @localhost to @postgres in main.py and database.py. anyone who did that first has to switch it back here, since the app now runs on the host. a one-liner would save them a confusing connection error.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants