Proposal: Integration of pact-jvm-mock into pact-jvm

[ludorival]

Overview

I've developed pact-jvm-mock, a library that automatically generates Pact contracts from existing mocks (Mockk, Mockito) in Kotlin/Java applications. The library aims to reduce the barrier to entry for contract testing by leveraging developers' existing mocking code.

Key Features

1. Seamless Integration with Existing Mocks: Minimal code changes required - primarily replacing every with uponReceiving in existing mock definitions.

fun `should intercept simple stub`() {
    given {
        uponReceiving {
            restTemplate.getForEntity(any<String>(), eq(String::class.java))
        } returns ResponseEntity.ok("Hello World")
    } `when`{
        restTemplate.getForEntity(TEST_API_1_URL, String::class.java)
    } then {
        with(getCurrentPact(API_1)!!) {
            assertEquals(1, interactions.size)
        }
    }
}

2. Multiple Mock Framework Support: Works with both Mockk (Kotlin) and Mockito (Java), with an extensible adapter system.

3. Spring Integration: Built-in support for Spring RestTemplate with matching rules and provider states.

fun RestTemplate.willReturnUserProfile() = uponReceiving {
    getForEntity(match<String> { it.contains("user-service") }, UserProfile::class.java, *anyVararg())
} withDescription { 
   "get the user profile" 
} given { 
   state("The user has a preferred shopping list", mapOf("userId" to USER_ID)) 
} returns 
    ResponseEntity.ok(
        USER_PROFILE
    )

4. Deterministic Mode: Optional strict mode to ensure consistent contract generation.

object DeterministicPact : PactConfiguration("shopping-list", SpringRestTemplateMockAdapter()) {
    override fun getPactDirectory(): String = "./src/test/resources/pacts-deterministic"
    override fun isDeterministic(): Boolean = true
    
    override fun customizeObjectMapper(providerName: String): ObjectMapper? = 
        NonDeterministicPact.customizeObjectMapper(providerName)
}

Benefits

1. Lower Barrier to Entry: Developers can start with contract testing without learning new syntax, using their existing mock definitions.
2. Reduced Duplication: No need to maintain separate mock and contract definitions.
3. Gradual Adoption: Teams can incrementally adopt Pact by converting existing tests.

Current Status

• Fully functional with comprehensive test coverage
• MIT licensed
• Published to Maven Central
• Being used in production environments

Next Steps

I believe integrating this into the official pact-jvm project would provide significant value to the community. I'm happy to:

1. Adapt the codebase to match pact-jvm conventions
2. Add additional documentation
3. Work on any suggested improvements

Would you be interested in discussing this integration? I'm happy to provide more details or schedule a call to discuss further.

Repository: https://github.com/ludorival/pact-jvm-mock

[rholshausen]

Hi @ludorival, when you say "integrating this into the official pact-jvm project", what do you envision that to be? This becomes a module in the Pact-JVM repo, or the docs for it get incorporated into the pact.io website? Or do you mean integrating it with Pact-JVM code (I notice it has it's own code for generating Pact files)?

[ludorival]

Hi @rholshausen , thanks for your reply.
Before considering making this part of the Pact-JVM modules, I would like to get your feedback on whether it aligns with your vision for Pact. Specifically, I’d like to know if you see value in integrating it as a module or keeping it as a standalone library. Either way, I believe it could complement Pact-JVM well, and I want to ensure it aligns with the broader goals of the project.

If you think there’s potential, I’d be happy to discuss how we could collaborate further or explore ways to integrate this effectively. Your insights would be greatly appreciated.

[rholshausen]

Pact-JVM already has a lot of modules, I wouldn't want to add more unnecessarily. You are publishing to Maven Central already, so I think a better approach would be to update your repo to use the Pact-JVM modules (so you get all the V3 + V4 formats) and then integrate your docs with docs.pact.io.

[ludorival]

Hello @rholshausen, as per your suggestion I have integrated pact-jvm:core modulehttps://github.com/ludorival/pact-jvm-mock/blob/9e41611c014410a28284ceab04dc51f76d2ac8dc/build.gradle.kts#L170
It is supporting now all pact versions by design.
Please guide me how to be integrated into docs.pact.io.

[rholshausen]

Ok, cool, let me find out about integrating your docs. It works by pushing your project markdown files to docs.pact.io (I think that is still running Docosaurus)

[mefellows]

This makes sense to me.

To setup and establish docs synchronisation, a few things are needed:

1. Update the dispatch receiver and job runs here (just copy an existing one)
2. Create a new workflow trigger in your project (example from Pact JS: https://github.com/pact-foundation/pact-js/blob/master/.github/workflows/trigger_pact_docs_update.yml)
   1. We'll need to create and share a new token for you to be able trigger the cross-project job
3. Create a new sync script in the docs project to pull in updates (example) that is triggered from (1)
4. Update the navigation to add the new items (not sure if you want this to be a new subsection of Pact JVM here or it's own top-level item. This probably needs some thinking)

3 and 4 can be tested locally first, and once you're happy we can then setup the automation (1 and 2).