Document matching rules and generators

[mefellows]

We have some rudimentary documentation on matching rules, however they are stuck in v2 land where only a few existed. We now have over 20 matching rules that could do with clearer documentation on behaviour.

Generators are not covered at all, despite the powerful features they bring to the table (e.g. the "from provider state" generator).

For example, a recent question about how each key works:

Each Key

Hi - I'm struggling to understand how to use the eachKeyMatches matcher properly; the documentation here is terse, and I haven't been able to find any working examples out there that really do a good job of explaining it. Any pointers much appreciated TIA.

Hey Alan
There is an example in the pact-js repo that may help
https://github.com/pact-foundation/pact-js/blob/master/examples/v4/matchers/consumer.spec.ts#L23
https://github.com/pact-foundation/pact-js/blob/master/examples/v4/matchers/provider.spec.ts#L16

consumer.spec.ts
https://github.com/[pact-foundation/pact-js](https://github.com/pact-foundation/pact-js)|pact-foundation/pact-jspact-foundation/pact-js | Added by GitHub

provider.spec.ts
https://github.com/[pact-foundation/pact-js](https://github.com/pact-foundation/pact-js)|pact-foundation/pact-jspact-foundation/pact-js | Added by GitHub
Also sent to the channel

Alan Boshier
Today at 4:17 AM
Thanks @Yousaf Nabi (pactflow.io) - I did take a look at those (they were the only examples I could find), but it didn't completely clarify for me how the rules array interacts with the exemplar object.

Yousaf Nabi (pactflow.io)
Today at 4:41 AM
Under the hood it is the eachKey matcher, from the version 4 specification, which might help surface some more results
https://github.com/pact-foundation/pact-specification/tree/version-4?tab=readme-ov-file#supported-matching-rules
The rules array is applied for any keys present in the req/response body. I don’t believe the matching rules are applied against the example value, which is used for a concrete example in the pact file (and can be returned via the stub server in later integration tests).
I would need to test to be sure
pact-foundation/pact-reference#303
appreciate the docs are a bit terse. Feel free to ask any questions, and if I can’t answer, Matt or Ron may be able to

#303 Validate example values for eachLike, eachKey, eachValue
https://github.com/[pact-foundation/pact-reference](https://github.com/pact-foundation/pact-reference)|pact-foundation/pact-referencepact-foundation/pact-reference | Jul 28th, 2023 | Added by GitHub