Skip to main content
View as Markdown

Network isolation in replay​

keploy mock replay answers the calls your tests make from the recording, so the tests run with no real dependency. This page shows what a replay keeps from the real network, the flags that let a call out on purpose, and how to tell whether one did.

Every output here is from Keploy 3.9.4 on Linux, in a Go project whose tests call a rates API on localhost:8090, with the recordings kept in the repository (--local). The output is trimmed: timestamps and lines that don't matter are cut. Tags such as #a9a4b64f98a3 change on every run, so this page shows them as #….

What a replay does with each call​

The callWhat the replay does
A connection the recording has: an HTTP or gRPC service, a database, a queueKeploy answers it from the recording. The real service is never asked.
A connection the recording doesn't haveIt never reaches the real service. An HTTP call gets 502 Bad Gateway, and the replay names the call. By default, the run fails when a test fails on that answer, or with --strict. See A call the recording doesn't have.
A connection to a port on your machine that nothing listens on, and that the recording never callsIt fails with connection refused, as it would without Keploy.
A DNS lookup the recording hasKeploy answers it from the recording.
A DNS lookup the recording doesn't haveKeploy answers it itself. In a replay on your machine, the name's address is 127.0.0.1, so a call that follows goes to Keploy, not to the real host. See DNS lookups.
UDP that isn't DNS, ICMP (ping), and raw socketsKeploy doesn't intercept them: they reach their real destination. See What a replay doesn't intercept.

These flags let a call out on purpose:

FlagWhat it lets out
--on-miss passthroughAn HTTP call the recording doesn't have goes to the real service. It isn't saved.
--on-miss recordThe same, and Keploy adds the call to the recording.
--pass-through-ports PORTEvery connection to that port, to any host, goes to the real destination. Keploy doesn't see it.
--allow-egress dnsA DNS lookup the recording doesn't have goes to the resolvers in /etc/resolv.conf.

A call the recording doesn't have​

The recording has the tests' call to the rates API. Say you then add a test that calls a ledger service on localhost:8091, and replay with the ledger service running:

keploy mock replay --local -c "go test -count=1 ./..."
🐰 Keploy: INFO  Replaying mocks for your test command  {"mock-set": "default", "program": "go", "args": 3, "on-miss": "fail"}
🐰 Keploy(agent): WARN mock mismatch: no matching mock for outgoing call {"protocol": "HTTP", "destination": "{}:8091 #…", "call": "GET /{}", …}
--- FAIL: TestBalance (0.00s)
balance_test.go:9: GET http://localhost:8091/balance?account=42: 502 Bad Gateway
FAIL
FAIL example.com/netiso 0.182s
FAIL
🐰 Keploy: INFO mock replay summary {"loaded": 1, "consumed": 1, "missed": 1}
…
Mock mismatch: [HTTP] GET /balance [path tag #…] → localhost:8091 [host tag #…]
…
🐰 Keploy: INFO test command exited non-zero; mirroring its exit code {"phase": "replay", "exitCode": 1}
🐰 Keploy: INFO this replay did not prove the tests run with the dependencies off {"mock-set": "default", "reason": "the test command failed"}

The ledger service was up, but the call never reached it: Keploy answered it with 502 Bad Gateway. To fix it, record again with the service running, or add the call with --on-miss record. Troubleshooting shows both.

A test that doesn't fail on the answer​

The run fails above because TestBalance fails on the 502. A test that doesn't check the answer passes, and by default, so does the run. Say the new test only logs what the ledger service answers:

func TestBalanceTolerant(t *testing.T) {
resp, err := http.Get("http://localhost:8091/balance?account=42")
if err != nil {
t.Logf("ledger call error: %v", err)
return
}
resp.Body.Close()
t.Logf("ledger answer: %s", resp.Status)
}
keploy mock replay --local -c "go test -count=1 -v ./..."
=== RUN   TestBalanceTolerant
tolerant_test.go:17: ledger answer: 502 Bad Gateway
--- PASS: TestBalanceTolerant (0.00s)
PASS
ok example.com/netiso 0.194s
🐰 Keploy: INFO mock replay summary {"loaded": 1, "consumed": 1, "missed": 1}
…
Mock mismatch: [HTTP] GET /balance [path tag #…] → localhost:8091 [host tag #…]
…
🐰 Keploy: INFO test command finished successfully {"phase": "replay"}
🐰 Keploy: INFO this replay did not prove the tests run with the dependencies off {"mock-set": "default", "reason": "1 call(s) matched nothing in the recording"}

The call still never reached the ledger service, and the replay names it. But this replay exits 0: only its last line says it didn't prove the tests run with the dependencies off. To fail such a run, add --strict:

keploy mock replay --local --strict -c "go test -count=1 -v ./..."
🐰 Keploy: INFO  mock replay summary  {"loaded": 1, "consumed": 1, "missed": 1}
…
🐰 Keploy: ERROR replay failed under --strict: recorded dependency calls were missed {"missed": 1, "next_step": "a dependency contract drifted; re-record the set (keploy mock record) or add the new calls with --on-miss record"}
🐰 Keploy: INFO this replay did not prove the tests run with the dependencies off {"mock-set": "default", "reason": "1 call(s) matched nothing in the recording"}

It exits 1.

Let a call out on purpose​

--on-miss passthrough​

With --on-miss passthrough, an HTTP call the recording doesn't have goes to the real service:

keploy mock replay --local --on-miss passthrough -c "go test -count=1 ./..."
🐰 Keploy: INFO  Replaying mocks for your test command  {"mock-set": "default", "program": "go", "args": 3, "on-miss": "passthrough"}
🐰 Keploy(agent): INFO real egress opened by onMiss passthrough (--on-miss passthrough): an HTTP call no mock answers goes to its real destination
ok example.com/netiso 0.130s
🐰 Keploy: INFO mock replay summary {"loaded": 1, "consumed": 1, "missed": 0}
🐰 Keploy: INFO test command finished successfully {"phase": "replay"}
🐰 Keploy: INFO this replay did not prove the tests run with the dependencies off {"mock-set": "default", "reason": "--on-miss passthrough lets a call the recording does not have reach the real dependency"}

The tests pass, but the replay says it didn't prove anything, because a call reached a real service. The recording still has only the rates call: the ledger call isn't saved. To save it, use --on-miss record instead, as the Python quickstart does.

--pass-through-ports​

--pass-through-ports keeps Keploy out of every connection to the ports you name. The kernel hands them to the real destination, so Keploy doesn't answer, record or report them:

keploy mock replay --local --pass-through-ports 8091 -c "go test -count=1 ./..."
🐰 Keploy: INFO  Replaying mocks for your test command  {"mock-set": "default", "program": "go", "args": 3, "on-miss": "fail"}
🐰 Keploy(agent): INFO real egress opened by bypassRules naming only a port: any host on these ports; the kernel hands their connections to the real destination, so keploy neither serves nor reports them {"ports": [8091]}
ok example.com/netiso 0.173s
🐰 Keploy: INFO mock replay summary {"loaded": 1, "consumed": 1, "missed": 0}
🐰 Keploy: INFO test command finished successfully {"phase": "replay"}
🐰 Keploy: INFO this replay did not prove the tests run with the dependencies off {"mock-set": "default", "reason": "bypass rules send calls to :8091 to the real service"}

With the ledger service stopped, the same replay fails the way the test would fail without Keploy, because the call goes to the real port:

--- FAIL: TestBalance (0.00s)
balance_test.go:9: Get "http://localhost:8091/balance?account=42": dial tcp [::1]:8091: connect: connection refused

Keep these in mind:

  • The flag names a port, not a host. --pass-through-ports 443 lets every call to port 443 out, whatever its host.
  • Keploy doesn't save the flag. A record with --pass-through-ports 8091 leaves the ledger call out of the recording, and a replay without the flag then answers that call with 502 Bad Gateway. Pass it to the record and to every replay.

--allow-egress dns​

--allow-egress dns sends a DNS lookup the recording doesn't have to the resolvers in /etc/resolv.conf. DNS lookups shows what it changes. dns is the only value Keploy takes. Any other is refused:

keploy mock replay --local --allow-egress web -c "go test -count=1 -v ./..."
Error: test.allowEgress entry "web" is not one keploy can open; the supported entries are: dns

The replay exits with code 1, before it runs the tests.

DNS lookups​

A test that looks up example.com, a name the recording doesn't have, gets its real addresses without Keploy:

go test -count=1 -v ./...
=== RUN   TestLookup
lookup_test.go:10: example.com: [104.20.23.154 172.66.147.243 2606:4700:91b5:72db:f276:0:ef6b:ff98] <nil>
--- PASS: TestLookup (0.00s)

In a replay, Keploy answers the lookup itself:

keploy mock replay --local -c "go test -count=1 -v ./..."
🐰 Keploy(agent): INFO  in this replay, a DNS query no mock answers is forwarded only to a resolver inside the replay's own network, and only for a name that network owns (one docker's resolver holds for the replay's networks, as the keploy CLI lists them, or one under the cluster domain); keploy answers every other name itself, and the host's and public resolvers are not asked
…
=== RUN TestLookup
lookup_test.go:10: example.com: [127.0.0.1] <nil>
--- PASS: TestLookup (0.00s)
=== RUN TestRate
--- PASS: TestRate (0.00s)
PASS
ok example.com/netiso 0.182s
🐰 Keploy: INFO mock replay summary {"loaded": 1, "consumed": 1, "missed": 2}
…
🐰 Keploy: INFO this replay ran with every dependency answered from the recording {"mock-set": "default", "served": 1}

The two misses in the summary are the lookup's two queries, one for an IPv4 address and one for an IPv6 address. A DNS miss doesn't fail the replay.

The first line says where a lookup can go. In a replay on your machine, Keploy answers every name the recording doesn't have. In a Docker or Docker Compose replay, a container or service name on the replay's Docker network still goes to Docker's resolver.

With --allow-egress dns, the lookup goes to the real resolvers:

keploy mock replay --local --allow-egress dns -c "go test -count=1 -v ./..."
🐰 Keploy(agent): INFO  real egress opened by test.allowEgress (dns): a DNS query no mock answers is forwarded to the resolvers in resolv.conf  {"resolvers": ["1.1.1.1", "8.8.8.8"]}
…
=== RUN TestLookup
lookup_test.go:10: example.com: [104.20.23.154 172.66.147.243 2606:4700:91b5:72db:f276:0:ef6b:ff98] <nil>
--- PASS: TestLookup (0.01s)

To set it for every replay, add it to keploy.yml:

test:
allowEgress: [dns]

A replay with no --allow-egress flag then prints the same real egress opened by test.allowEgress (dns) line. The flag, when you pass it, replaces the list in keploy.yml.

In Keploy 3.9.4, a replay that sent a lookup to the real resolvers still ends with "this replay ran with every dependency answered from the recording". Look for the real egress opened by line to know.

Tell whether a replay reached the real network​

  • The last line. "this replay ran with every dependency answered from the recording" means the recording answered every connection the tests opened. It doesn't count lookups sent out with --allow-egress dns, or the traffic in What a replay doesn't intercept. "this replay did not prove the tests run with the dependencies off" gives the reason, such as bypass rules send calls to :8091 to the real service.

  • The real egress opened by lines. Each flag that lets something out prints one line that starts with real egress opened by, says which flag, and says what it lets out. Search the output, or the log file the replay names, for it.

  • keploy mock status. Its summary repeats the reason:

    summary:  1 recording(s); not yet proven to run with the dependencies off: default (bypass rules send calls to :8091 to the real service).
  • keploy/default/last-replay.yaml. It has isolated: false, the reason in isolationNote, and the bypassed ports in bypass. The reference lists its fields.

Every replay also prints this line, with a port that changes on each run:

🐰 Keploy(agent): INFO  real egress opened by keploy mock's agent API port: any host on these ports; the kernel hands their connections to the real destination, so keploy neither serves nor reports them  {"ports": [62514]}

It is the port that keploy mock uses to talk to its own agent, which Keploy keeps out of the replay so that it can reach the agent.

What a replay doesn't intercept​

In Keploy 3.9.4, a replay intercepts TCP connections and DNS. UDP that isn't DNS, ICMP and raw sockets aren't intercepted: they reach their real destination, and Keploy doesn't report them.

Here, a test sends a UDP datagram to an echo service on 127.0.0.1:9999, and the replay doesn't stop it:

keploy mock replay --local -c "go test -count=1 -v ./..."
=== RUN   TestUDP
udp_test.go:24: udp answer: "ping"
--- PASS: TestUDP (0.00s)
PASS
ok example.com/netiso 0.170s
🐰 Keploy: INFO mock replay summary {"loaded": 1, "consumed": 1, "missed": 0}
🐰 Keploy: INFO this replay ran with every dependency answered from the recording {"mock-set": "default", "served": 1}

With the echo service stopped, the test gets the real port's answer:

    udp_test.go:22: no answer: read udp 127.0.0.1:43821->127.0.0.1:9999: read: connection refused

So the last line's "every dependency answered from the recording" counts TCP and DNS only. If your tests send UDP, such as StatsD metrics or syslog, point them at an address on your machine while they run.

See also​