[slayerjain]

What

keploy-junit5/, a JUnit 5 (Jupiter) extension that lets keploy mock record and keploy mock replay
judge a JUnit suite test by test. keploy judges each test once the framework tells it where the test
begins and ends; go-sdk's keploytest and @keploy/playwright do that for Go and Playwright, and JUnit
had nothing. The extension speaks the same wire (keploy's scope protocol v1: claim, begin, end). keploy
keeps every rule, and the extension decides nothing.

Setup is one line in src/test/resources/junit-platform.properties
(junit.jupiter.extensions.autodetection.enabled=true), then
KEPLOY_PROVEN=1 keploy mock record|replay -c "mvn test". Without keploy (KEPLOY_MOCK_AGENT unset or
off) it does nothing.

How it maps onto JUnit

• Claim: once per test JVM, before the first class's @BeforeAll.
• Begin: a BeforeEach callback of the extension. Autodetection registers it at the root, so it runs
  before every other extension's BeforeEach callback and every @BeforeEach method, and after the
  class's @BeforeAll.
• Skip: a test keploy set aside is aborted with keploy's reason, and none of its own methods run.
• End: an AfterEach callback, which runs after every other one. The outcome comes from
  ExtensionContext.getExecutionException(): no exception is passed, an abort is skipped, and anything
  else is failed. When keploy fails the test at its end, the test fails with keploy's text; if it had
  already failed, keploy's text is added to that failure as a suppressed exception.
• ID: <class binary name>::<JUnit's method name>, with the invocation index for parameterized
  and repeated tests, e.g. com.shop.OrdersTest::price(java.lang.String)[2]. Each invocation of a
  @ParameterizedClass (JUnit 5.13 and later) runs each test of the class as a test of its own, with the
  class's invocation index before the method: com.shop.OrdersTest::[2]price(java.lang.String).

Fails closed

Each of these fails the affected tests or classes with the reason. No Jupiter test runs unjudged:

• an agent answer the extension cannot trust (non-2xx, no or wrong protocol version, unreadable, over
  1 MiB);
• a failed claim, which fails every class (a plain 404 names KEPLOY_PROVEN=1);
• a KEPLOY_MOCK_AGENT that is not an http URL;
• registration with @ExtendWith only;
• JUnit's parallel execution;
• a @TestFactory, whose dynamic tests share one BeforeEach/AfterEach pair;
• a test begun twice in one JVM (a rerun, or a second @Suite that selects the same class).

A test run through a JUnit Platform @Suite has the ID it has when it runs directly: the suite and its
engine are not the test.

Limits

• One test JVM at a time: keploy refuses a second claim.
• A JVM cannot change its own environment, so it does not export KEPLOY_TEST_PID. A process its
  tests start that also claims is refused by keploy.
• Only Jupiter tests are judged. The tests of every other JUnit Platform engine run unjudged, as without
  keploy: JUnit 4 tests on the Vintage engine, and Spock, Kotest, jqwik and Cucumber tests. No other
  engine calls a Jupiter extension.

Packaging and publishing

It is a Maven project of its own, not a module of the root pom, released on its own tag with its own
version: release.yml (v*.*.* tags) builds and deploys only the root's modules and never this one, so an
agent release does not republish the extension and the extension can ship a fix without an agent release.
It adds no runtime dependency beyond the suite's own JUnit (the JSON of the wire is read by a small strict
reader in the package). Its coordinates are io.keploy:keploy-junit5.

• .github/workflows/keploy-junit5-release.yml publishes to Maven Central from a pushed tag
  keploy-junit5-vX.Y.Z. It runs junit5-sdk.yml first (the rows on every JDK and JUnit leg, and the e2e
  lane). It refuses a tag that is not keploy-junit5-vX.Y.Z with X.Y.Z a release version with no leading
  zeros, and refuses to start, naming each one, when a secret it needs is not set. It then sets the pom's
  version to X.Y.Z for that run only, and runs mvn -P release clean deploy: the jar with its sources and
  javadoc jars, each signed, deployed by central-publishing-maven-plugin. Every action in it and in
  junit5-sdk.yml, whose rows run in the same workflow run, is pinned by commit: the publish job holds the
  signing key and the Central token.
• The pom gains what Central requires and the root pom already has (developers, scm) and the root's
  release profile (sources, javadoc, gpg, central-publishing, the same plugin versions). Its scm
  connections name the git provider (scm:git:...), which the root pom's leave out.
• What it needs: the repository secrets release.yml reads, under the same names: CENTRAL_USERNAME and
  CENTRAL_PASSWORD (a Central Portal user token for the io.keploy namespace), MAVEN_GPG_PRIVATE_KEY
  (the ASCII-armored release key, id 8541784E4EC36FB8) and MAVEN_GPG_PASSPHRASE. The repository's
  secrets list today shows MAVEN_USERNAME, MAVEN_PASSWORD, GPG_PRIVATE_KEY and GPG_PASSPHRASE, not
  these four, and no organization secret is visible to it. Until the four are set (as repository or
  organization secrets), both this workflow and release.yml's Central deploy refuse to publish; this one
  names the missing secrets.
• Pull requests that touch keploy-junit5/ run the release build as a dry run (the release profile,
  unsigned, no deploy) and check that the jar, sources jar and javadoc jar are built.
• Nothing is published by this PR, and keploy-junit5 is not on Maven Central yet, so the README says to
  install it from this folder with mvn install.

Tests

84 rows (mvn verify in keploy-junit5/):

• JSON reader and writer;
• the agent client against a fake agent;
• the environment rules;
• real JUnit runs of fixture suites through EngineTestKit (order around other extensions and lifecycle
  methods, outcomes, skip, keploy's fail, agent errors, claim failure, refusals, rerun, names, and tests
  run through a JUnit Platform @Suite);
• a @ParameterizedClass, with a nested one inside it, compiled and run by the row itself on JUnit 5.13
  and later (the rows also build on 5.10, which has no class templates; there the row checks that JUnit is
  older than 5.13).

The new keploy-junit5 workflow runs them on JDK 8 + JUnit 5.10.5, JDK 17 + 5.14.4 and JDK 21 + 6.1.3;
all 84 pass on each of those three.

e2e (keploy-junit5/e2e/lane.sh, CI job e2e, JDK 17): the extension installed with Maven into the
lane's own Maven repository, used by a small JUnit 5.14.4 suite whose tests call a provider over HTTP (a
@Nested class and a parameterized test among them), run with Maven offline under keploy 3.8.106 (the
enterprise build, which judges each test under KEPLOY_PROVEN=1; pinned by version and sha256).

• Without keploy the suite passes as plain JUnit, and nothing says keploy.
• Record keeps each test's calls under its class and JUnit's name of it
  (shop.OrdersTest$Books::pricesABook(), shop.PaymentsTest::chargesACard(int)[1]).
• Replay with the provider stopped passes all 3.
• A call with no recorded answer fails only its own test, with keploy's miss added to its failure.
• A recorded call the test no longer makes fails only that test, with keploy's text.
• A quarantined test is skipped by JUnit, with keploy's reason in Surefire's report, and the replay passes.

The README also says what the lane showed a user needs: keploy.yml's mock.command and mock.name, and
--local to keep the recording on disk.