https://pact.io logo
Join Slack
Powered by
we're in a situation in which we have several team...
# general
u
we're in a situation in which we have several teams writing consumer tests, while others are writing provider tests, and right now the solution to that is to "hop on a zoom call" but that's ad-hoc a best
b
Contracts are definitely not a replacement for conversations 🙂 (as it says in the FAQ)
it might be a good idea to come up with a naming scheme, and document it somewhere, so you don't have to have to have the discussion from first principles every time
u
right, not trying to prevent conversations 🙂
but I'm thinking that agreeing on strings for everything, and hoping that they still match 6 months later is a bit brittle
and sadly, in my experience, documentation rots faster than software
just trying to formalise and add more visibility to these agreements
đź’Ż 1
if you're interested I have a proposal; in fact I'd love to run it by you folk
âś… 1
b
I don't work for Pact, but I think everyone is always keen for improvement ideas ^_^
đź’Ż 1
I think the reason there's no formal guidance around it, from the Pact side, is that there are so many different ways people like to do things, and there's not a one-size-fits-all solution. All of the ways I've seen people add structure to state names encodes significant abstraction that's not rarely warranted for all other users.
That said, there's a bit more structure added in more recent versions, with support for lists of state names, and additional maps for metadata. This seems to get people a lot further down the path.
y
Would love to hear your ideas @Ulises Cervino! I think I would like to see the ability to easily see provider states in use at a glance for a provider, and which consumers are using any given state description. This would allow me to strike up the right conversations, if someone isn't using the right string on the consumer side, or to help authors find existing states to use. The consumers often may not have access to the provider codebase explicitly so can only traverse other contracts.
u
the tl;dr for what I had in mind is to have a broken openapi spec describing (enums) consumer/provider names, provider states, and variable names
possibly one of the biggest benefits there is code generation + IDE autocompletion for discovery of these things
what I've seen at work is that many people write both consumer and provider tests, and so they can have a central class (in Java for instance) with enums for these
but that's in a single repository, single team, etc. It's easy.
we (my team) are in a position where consumer tests will be written by other teams, in 2+ languages, and we need to coordinate and communicate names, states, variable names, with everybody
so I'm planning on writing this spec and distribute it + give instructions for code generation
m
Just thinking for better possibilities here, because these seem brittle and look like workarounds (which may be of course acceptable in the short term)
What if all of the provider states and any associated parameters/data could be enumerated within the Pact Broker (probably attached to a provider-role pacticipant), and then annotated from within the Pact Broker with what their purpose is? e.g. a form of “data dictionary”
I’m not sure I follow the OAS argument, how would IDE code completion help here? Also, why you would need the consumer/provider names in an OAS given you can see them in the Pact Broker already? What additional value to you get from it being in the OAS? I’m guessing you may want a way to control what names can be used or control who can create them?
u
a central registry is the general concept, however not every consumer/provider is initially integrated with the broker, so using the broker as a central repository of names/state-names/variable-names is a fine idea, but might not work all the time
regarding IDE completion, OAS is only the source of truth, each participant would have to generate code (the models -- which would be nothing but enums) before they can get their IDE to auto-complete things
further benefits of distributing OAS as an artefact is versioning, auto-upgrades (via automated jobs or bots like renovate https://github.com/renovatebot/renovate)
m
I must be missing something sorry, i’m still confused about the relationship of the OAS -> consumer/provider names, states, variables etc. Could you perhaps show me what the OAS would contain to solve this problem?
u
yes, of course, let me give you an example. Say we have consumer 
C
and provider 
P
. In pact-jvm you annotate tests with 
@Consumer("C")
and 
@Provider("P")
on both ends. Further, in the consumer you write stuff like 
.given("an expected state for the provider to be in")
and in the provider tests you also add 
@State("an expected state for the provider to be in")
and so on.
now imagine the team of the consumer saying "you know, "C" is a bad name for our consumer, it should be "VeryCoolConsumerC" instead!" the team agrees and change their tests
now only older pacts (for consumer "C") are being verified by the provider, and not the new ones
of course this can be solved by a "quick zoom call", which I find brittle (I can share stories about OAS and quick zoom calls -- tl;dr don't trust people, trust code)
my proposal: have an OAS with stuff in it such as
Copy code
components:
  schemas:
    Consumer:
      description: Service consumer
      enum:
        - basket-storage
        - basket-checkout
        - flight
from that you can generate code, in Java you'd end up with an enum 
Consumer
, with instances such as 
BASKET_STORAGE
(you get something similar for JavaScript too)
so, what's the point? now if you depend on the OAS (and you generate the code) in your project, with the help of your IDE you can discover participant names, provider states (there'd be a section in the OAS for provider states), and more.
say someone changes their consumer name from 
C
to 
VeryCoolConsumer
, when a new version of the OAS is published (and people should always auto-upgrade) now you'd get compilation errors
so this raises the visibility of an actual issue (newer pacts aren't being verified)
guess how many pipelines I've seen where people allow the verify-job to fail because it couldn't find a contract or something similar? (too many, and this is of course an issue in and of itself eh)
m
It feels like you’re just moving the problem around - yes sure the OAS has code gen, but now you: 1. Need to update all of the places you use Pact to be aware of the OAS / schema 2. Need a way to manage the OAS so that you always have the latest version 3. Need a way to version the OAS reliably 4. … without those things the risk of having out of date information anyway. The pact broker already has this information, there must be another way! (please don’t not do this if you think it will work for you of course! But I’m trying to take your requirement and extrapolate it to a general solution that might benefit others)
u
yes, great observations, we have 1-3 sorted out, but the out-of-sync issue is still there
đź‘Ť 1
sorry, was in a meeting and that's why I was a bit terse: while the info is in the broker, a participant might move on from what's in there (name changes, state-name changes, and even things like variable names in expressions which aren't in the broker -- they're in the pact alone)
the point of the shared registry (in OAS form in my head right now) is to raise visibility for when there's change, and to add discoverability. This sort of mechanism also doesn't really rely on a broker, so in principle you could use this + S3 buckets for sharing pacts (I know you lose a lot of functionality if you do this though)
Open in Slack
PreviousNext
Powered by