has joined #contract-case

has joined #contract-case

has joined #contract-case

has joined #contract-case

has joined #contract-case

Hey all! I?m Dan, looking to take a stab at porting a Kotlin DSL for Contract Case. Sorry in advance for any spam as I ask all the silly questions

First up is about defaults/required properties for configuration in the DSL?s. There is some mention of default values in the docs. I?m unsure if I should be: ? Implementing those defaults in the DSL layer ? Using the type system to help me enforce required properties, or leaving that to core validation ? Duplicating the documentation - I would like consumers (of the library) to be able to get a good understanding of required values and defaults directly from the Kdoc in their IDE

? The defaults are applied by the core ? The core does validation of required properties (on the todo is to do this all in one place - it's currently a bit spread as and when the properties were queried, so I think there may be bugs. Assume the core does it, and let me know / open an issue / make a PR to case-core if it doesn't) ? Yeah, currently the documentation is duplicated in each DSL layer. I don't like this at all, so if you think of something better, I'm all ears

Following the https://github.com/case-contract-testing/contract-case/blob/main/docs/maintainers/GeneralDesign.md I'd prefer a slightly annoying maintainer experience (manually updating all the docstrings) in exchange for a better user experience

What I've been doing while working on the Java DSL is updating https://github.com/case-contract-testing/contract-case/blob/main/docs/maintainers/AddingDsl.md every time I find I need to make a choice or find something missing

(these answers should totally go in there - if you want, you can easily put them in with github's instant PR edit button - or I can do it later)

Another separate thread for this one since it?s a bit specific: ? Skipping passing nulls to the boundary layer for unset values The Java DSL https://github.com/case-contract-testing/java-dsl/blob/15d71cfbb16576aa1d113220738a1416e518dd97/src/main/java/io/contract_testing/contractcase/BoundaryConfigMapper.java#L60 conditionally maps values to the boundary if they are not null. ``` if (config.brokerBaseUrl != null) { builder.brokerBaseUrl(config.brokerBaseUrl); }``` Is there a reason we don?t map everything anyway, even if the property is null? Looking at the Jsii types it seems like these should be nullable for the most part

It would be AWESOME if all the javadoc / docstrings / tsdoc etc was kept up to date automatically, but I don't know how to solve that - even if we had a way to instantly update everything from a master source, you don't actually want exactly the same text in each language

Yeah there are some minor variations depending on the ergonomics of each DSL, so a shared javadoc generation thing would probably have its own headaches

That's just personal preference. I wanted it to be consistent, so I did each one explicitly. That particular one does no mapping, but it's implicitly: ``` if (config.brokerBaseUrl != null) { builder.brokerBaseUrl(BrokerBaseUrlMapper.map(config.brokerBaseUrl)); }``` I wanted the mappers not to have to know whether or not they have the thing

Also I don't really know how to Java any more?

You don't have to do it the same way, as long as the exposed interface is the same

(to both the user and `case-boundary`)

With that explicit check you don't have to start each mapper with `if(thing == null) return null`

Probably there's a MUCH nicer way to do it in kotlin :raised_hands:

> The core does validation of required properties The main reason I ask about this one specifically, is that we can get help from the type system in the kotlin DSL, so users get faster feedback on mis-use

Yeah in kotlin I?m doing something like: ```build(ContractCaseBoundaryConfig::builder) { testRunId(testRunId) providerName(providerName) consumerName(consumerName) // ... }``` So just wanna save a bunch of ```if (brokerBaseUrl != null) brokerBaseUrl(brokerBaseUrl)```

Right yep

I like it

I think in Java I'd have to do that check anyway, maybe not for primitives

Yeah....

So, what I did there is - the boundary is very permissive. Like, it lets you pass ANYTHING as the mock example description

which is wrong. You can't actually pass anything.

My thinking is that the DSL would be more restrictive

there's a type for `AnyMockDescription`

and there's an `AnyMatcher`, but currently that's not used

So, I think that it's ok to make the type system helpful where possible

see the enums in Java, whereas TS has strings

There's one place where you have to do validation, which is the combinations of testResponse and trigger functions

since these must be combined before being passed to the boundary (as the boundary can't take the native object returned by `trigger` and pass it to `testResponse`), the only place we can validate them is in the DSL

hmm ok I?ll keep an eye out for that exception

Will favour language idioms over strictly not validating anything - might bite me later but we?ll see

Ok and for the collection types like the map of state handlers, do we prefer a null, or an empty map?

Either should work. (Implementation details: The definition at the boundary is expecting a null, but it becomes an empty map when it goes into the core anyway)

Yeah I figured as much, cheers

The value here is in not needing to update several places when the acceptable values change

But it's more valuable to be helpful to the user

Yeah totally understand wanting to keep as much as possible in core

I didn't do it in the type system, because the autotranslation only accepts a subset of Typescript.

(eg, it doesn't let you do unions, which is what you would do idiomatically in TS)

The ts-dsl would allow for this though right

Also: A validation error at runtime is more helpful.

It does.

Runtime validation means we can give arbitrary error messages. Whereas trying to do it in the typesystem just leaves users being like "why isn't there a constructor with this invalid option combination" or something

For preferences - I prefer nothing is null, ever. But I didn't want to do a lot of `Optional<>` in Java

but that's just preference. I won't make you do it if you prefer something else.

The TS dsl won't let you do: ```someProp: undefined``` but it will let you omit `someProp`

Yeah agree

I thought you might :joy:

has joined #contract-case

Kinda why I want defaults in the DSL layer

Also, @dan.nichols52 - I mentioned this elsewhere, but it should go here too - frustratingly the JSii boundary won't work at all until https://github.com/aws/jsii/issues/4133. And I think we (I?) are going to have to fix it: https://github.com/aws/jsii/issues/4133

How hard is it to expose constants from Jsii. Could rely on boundary instead of hardcoding in dsl

However, worst case, if you build something to the `case-boundary` API, then it's replaceable - since all that layer does is contact the core.

Depending on how that issue goes I might look into a JavaScript jsii binding instead of JVM, since I was going to have to do that to support kotlin multiplatform anyway

Yep. I can expose defaults

That's a really good idea

There already are exposed constants for acceptable values for `logLevel`, `publish`, etc

I think those are already in use to build enums in java DSL yeah?

Javascript JSii is just the JS lib anyway

(with no translation)

Ahh right ok

the TS DSL is in the main repo, under packages/contractcase-jest-dsl (I think)

Hmm actually I think I need a Jsii target for every kotlin target I want to support. So in the end need JavaScript, and jvm

yeppers

Can I confirm something from the docs? https://case.contract-testing.io/docs/reference/triggers#providing-triggers-during-contract-definition. Gonna paraphrase the docs to see if my understanding is correct. The 3 ways to define a trigger are: 1. In the `runExample` arguments (for a successful response) 2. In the `runRejectingExample` arguments (for an unsuccessful response) 3. A group of named triggers in the ContractCaseConfig object (for contract verification) The docs has the usage of (1) as: ```await contract.runExample({ states: [...], // These `...` are not spreads, just for brevity definition: willSendHttpRequest(...), }, { // Presumably the ContractCaseConfig object as an override for the parent config trigger: (config: HttpRequestConfig) => {}, testResponse: (user) => {} })``` But looking in https://github.com/case-contract-testing/contract-case/blob/1eeef00cf6eef5ac942003544d0496fd466effa2/packages/case-core/src/index.http.client.define.spec.ts#L144, the triggers are defined as: ```contract.runRejectingExample({ states: [...], definition: willSendHttpRequest(...), trigger: (config: HttpRequestConfig) => { ... }, testResponse: (user) => { ... }, });``` Are both of these patterns going to be supported? Can I converge on just one of these in the DSL? Looks like the former example is more aligned to the boundary schema, but the latter feels more natural. From https://github.com/case-contract-testing/contract-case/blob/main/docs/maintainers/AddingDsl.md#implementing-the-contractdefiner-class there is a TODO. Is this just going to say that a trigger needs to be paired with a response (whether success or rejecting), and you can?t have one without the other? > TODO: Describe how to map trigger / testResponse - this is the only place where you may throw a `CaseConfigurationError`

> Are both of these patterns going to be supported? Can I converge on just one of these in the DSL? No, just the `{states, defintion}, {...config}` one. The reason for this is because the first argument (states/definition) is just data, the second (config) is test setup. Triggers and test response functions are just > But looking in some examples in the codebase, (....) That's an internal test, not a test written using the DSL. The API is different (I would like to update it to match the boundary API though - there's no technical / conceptual reason for it to be different). > A group of named triggers in the ContractCaseConfig object (for contract verification) One clarification - the main usecase for this is verification, but it's also valid for definition. Eg, you could define all the triggers at the top so you don't have to repeat them if you've got a lot of different states for the same endpoint.

Thanks for the response

> From the DSL ContractDefiner setup instructions there is a TODO. Is this just going to say that a trigger needs to be paired with a response (whether success or rejecting), and you can?t have one without the other? Yes, that's right. It has to be done in the host code (Kotlin) because JSii can't handle arbitrary host objects - so the core can't take the `trigger`'s return value and pass it to the `testResponse` function

Ultimately, `trigger` and `testResponse` will be removed from the core

This substantially simplifies it

That?s why we are allowed to throw ContractCaseConfigurationError there

Yes

> No, just the {states, defintion}, {...config} one. The reason for this is because the first argument (states/definition) is just data, the second (config) is test setup. Triggers and test response functions are just If you think this doesn't make sense, I'm open to an alternative DSL

It?s a bit confusing to me, just need to figure out how to say why

er, that should say: > Triggers and test response functions are just test configuration

The point is the first argument is what's actually going in the contract

everything else doesn't.

I think the confusing thing is that in a global context, the group of triggers makes sense - they?re all named, and they can have success or error functions, or both

But in the runExample context, you?re allowed to have a single trigger (and paired response function) in the top level config object

So are the triggers on the individual versions named/keyed? Do they need to be?

> But in the runExample context, you?re allowed to have a single trigger (and paired response function) in the top level config object Yep! That's unlikely to be common. But you can. You should be able to say: ```defineContract(triggers) <-- where triggers doesn't have testResponse functions``` then: ```runExample(whatever, { testResponse: someFunc} )``` But at the moment, you can't.

> So are the triggers on the individual versions named/keyed? Do they need to be? Yes

Otherwise the core doesn't know which ones to use

Oh right! Let me get you a link that tells you how to do that

````${requestName}::${responseName}````

So, triggerKey, testResponseKey, joined with `"::"`

Right so they?re implicitly keyed from the ITriggerFunction

Explicitly?

Not implicit

^ that code is in the boundary

Ah, no, not from `ITriggerFunction`

The keying is implicit to the end user right

> Sets the value of getTriggerAndTest > Params: > triggerAndTest ? Call the native trigger and test function (if any) for this interaction pair. Keyed by ${requestName}::${responseName} > Returns: > this This is the boundary config option I?m looking at

> ^ that code is in the boundary No it isn't. It's in the jest package

> Keyed by ${requestName}::${responseName} oops.

This line should be deleted

I still don?t get how the `triggerAndTest` config can be keyed by only passing in an ITriggerFunction

there's no key for `triggerAndTest`. It doesn't need to be keyed

Sorry about that, documentation is wrong

So keying happens in `triggerAndTests` (I have that in my dsl), but not in `triggerAndTest`

Ok so no keying for `triggerAndTest` does make sense, but that means it should only ever be usable from `runExample` and `runRejectingExample` right?

And not on the global config object?

Fixed the doc

> So keying happens in triggerAndTests (I have that in my dsl), but not in triggerAndTest Correct

> Ok so no keying for triggerAndTest does make sense, but that means it should only ever be usable from runExample and runRejectingExample right? Well. Yes ish. You could define it at the top level. It would work.

You might use that if you only have one endpoint but like 5 tests

you'd put `trigger` at the top, and then `testResponse` in each test

So you have the same trigger pair for every test

oh

No

Same setup

Different assertions

So um, confession time: The undocumented bits might be the trickiest

You have to remember the main config object and check it for the trigger / testResponse / testErrorResponse when you're looking to see if you have them

I might not have implemented that in the Java one :confused:

Yeah I?m following the java dsl for the most part :sweat_smile:

Ok so that validation needs to happen on the merged config

I guess the BoundaryContractDefiner doesn?t do that internally?

> Yeah I?m following the java dsl for the most part It's not fully complete, because at the moment I can't test it

It can't. Because they're joined at that point.

Yeah I notice I need to map the matchers which aren?t in the java version yet

I just looked at the TS DSL

Ah!

They are

You can just use the JSii package

Yeah you pass additional config to definer.runExample right

The TS DSL needs to be updated to use the JSii package

instead of the other way around

You could build builders for them

but it will be a lot of work

~So my plan~ scratch that I have no plan

in Kotlin, you'd be better off just using the constructor, I think ```ArrayEachEntryMatches(AnyString("foo"))``` etc

So the matchers do nothing. They are only data.

There's no behaviour. They produce objects that can be serialised to JSON. Unfortunately, because the properties are not valid names in most languages, they don't get builders built for free by JSii

Ok, will see about the matchers when I get there

The Java test that I have there is the best example of how to use them

....it's possible I didn't commit that

because it doesn't work

I will check after work

Yeah fair

No stress

Worst case I'll put it on a branch for you

The triggers are still confusing me

In java dsl world, `IndividualSuccessTestConfig` ~must~ may define a `trigger` and a `testResponse` pair, but that?s not technically right, because you may have defined a top level `trigger` on the top level config?

Yes

I messed that up

I remember fixing it though. I wonder if it's fixed on the non-pushed code

Ok so a lone `trigger` is valid on `ContractCaseConfig`

Yes, in isolation

no, in aggregate

if that makes sense?

Yeah but (at least in java), the contract definer doesn?t do any aggregation of config

Yep. The only reason you would need to do that is for triggers.

I don't think the TS DSL does either.

So should the mapSuccessExample validation be removed from the dsl?

But they both should.

Oh so the DSL?s _should_ be doing config aggregation

Yes, only for that field

it's the only one it needs to know about

it's a really annoying leaky concern.

There's no nice way to do it.

Ok so do that validation in `runExample` and `runThrowingExample` (somewhere down the mapping chain)

(as far as I can see)

Yep

Ok cool

Oh hey, I want to make tests for these

but I can't think of how to do it

I was thinking, a list of tests in one existing DSL

with "please port this to your DSL and make sure they all pass"

What do you think?

I have been thinking about making a `sample` or `example` module inside the dsl codebase that has a simple ktor server and client

Yeah, you'll need that for when you want to do tests

See the DSL test in Typescript

My plan was to make all of those consistent

so they have the same tests in all the languages

Can you just import a contract(s) from a different dsl and run the verification

You need two types of tests though

one for examples

(yes, for verification)

Not for definition right

one for examples, and one for all the different ways of executing tests.

> Not for definition right Yes, that's right

Because there are a lot of different ways to specify tests

Yeah saying, ?port all of these tests? is good, but you?ll get missed tests

eg, the core tests include: ```httpResponse({ status: 200 })``` and ```httpResponse({ status: "200" })``` and ```httpResponse({ status: httpStatus(200) })``` and ```httpResponse({ status: httpStatus("2XX") })```

> Yeah saying, ?port all of these tests? is good, but you?ll get missed tests My thinking was each test would get an ID. Then later I could parse the test output and produce a report of which IDs are missing for each language.

But again, I haven't really thought it through.

Yeah that can work

You?d just need review of each

Another thing I was thinking is to add some special matchers that exist only for testing

I would love to have example code used both in tests, and documentation

like ```runExample( CoreWillThrowConfigurationError, {config} )```

> I would love to have example code used both in tests, and documentation Yes, but the problem here is that you still need separate examples, as I mentioned above

hmm

Otherwise your "have a look at this file to see how to use it" is too confusing

because you could only read those if you already know how to use it, because there would be repeat specifications. Like: ```defineContract({triggers}) runExample(definition)``` and ```defineContract() runExample(definition, {triggers})```

I don?t know if there are tools for this, but something like the gradle docs would be good for this: https://docs.gradle.org/current/userguide/tutorial_using_tasks.html#sec:build_scripts_are_code Since there are multiple languages to do the same thing

What do you mean?

I?m conflating too many things, dw about me haahhaaha

If you're talking about the main docs, I was thinking that the docs would have tabs for each code example

I want code samples in documentation to be backed by concrete tests

Oh yes. That's definitely possible

That's a further down the line thing

Yeah totally

(I think)

I think we'll need some kind of parser so you can pull out bits for the docs. But I'm sure something like that exists already.

to avoid having the whole `import blah / define contract` in each `runExample` example

Ok so

fun aside

The `definition` part is just data, right?

Soooo when we implement `callFunction` mock types (which is like how Pact does message pacts), we could test the DSL with ContractCase

:exploding_head:

yes?

I don?t know hahah

Ok, so the Java DSL didn?t have the crash handler in it

it does now

I?ll paste an example of the Java DSL

Ahh ok nice cheers

it ?works? in that configuration errors are handled

Ok that?s good

@dan.nichols52 here?s an example use of the Java DSL: Some points: ? This is a modification of https://github.com/pactflow/example-consumer-java-junit ? The Java ContractCase DSL is SUPER wordy and unpleasant in places. Once I?ve fixed the JSii issue, I plan to do a parse to make it nicer to use / less wordy Define contract: ``` contract = new ContractDefiner( ContractCaseConfig.ContractCaseConfigBuilder.aContractCaseConfig() .providerName("Java Example HTTP Server") .consumerName("Java Example HTTP Client") .publish(PublishType.NEVER) .build());``` Run example: ``` @Test public void getProduct() { contract.runExample( new ExampleDefinition<WillSendHttpRequest>(new ArrayList<>(), new WillSendHttpRequest( HttpExample.builder() .request( new HttpRequest( HttpRequestExample.builder() .path("/product/10") .method("GET") .build() ) ).response( new HttpResponse( HttpResponseExample .builder() .status(200) .body( Map.of("name", new AnyString("product name"), "type", new AnyString("product series"), "id", new AnyString("5cc989d0-d800-434c-b4bb-b1268499e850") ) ).build() ) ).build())), IndividualSuccessTestConfig.IndividualSuccessTestConfigBuilder.<Product>builder() .withProviderName("Java Example HTTP Server") .withConsumerName("Java Example HTTP Client") .withLogLevel(LogLevel.DEEP_MAINTAINER_DEBUG) .withTrigger( config -> { try { return new ProductClient().setUrl( config.get("baseUrl").toString().replace("localhost", "127.0.0.1")) .getProduct("10"); } catch (IOException e) { throw new RuntimeException(e); } }) .withTestResponse( product -> { assertThat(product.getId(), is("5cc989d0-d800-434c-b4bb-b1268499e850")); }).build() );```

If you get as far as running it, this example above should produce the following log:

Oh yeah, also, there is currently no logging from `case-boundary`. I?m planning to put some in, at the `deepMaintainerDebug` level

Ok, I?ll post a similar example of the kotlin DSL when I get a chance, but am about to run off

Samesies

I?m gonna work on that bug on Monday

I think it will only require changes in every JSii package

(not actually, but?. maybe)

Seems like a pretty big overhaul change for jsii

?..yeah

I might be able to get away with just making one side non-blocking

Or we could just do an alternate approach and build a case-boundary that communicates with the core some other way

It?s possible that THAT could be done with JSii.

Published some new versions that fix JSii load errors: ```def caseCoreVersion = "0.13.0" dependencies { api "io.contract-testing.contractcase:case_example_mock_types:${caseCoreVersion}" api "io.contract-testing.contractcase:test-equivalence-matchers:${caseCoreVersion}" implementation 'io.contract-testing.contractcase:case_boundary:0.6.3'```

Breaking changes: ```import io.contract_testing.contractcase.case_example_mock_types.AnyMockDescriptor;``` becomes: ```import io.contract_testing.contractcase.case_example_mock_types.base.AnyMockDescriptor;```

There's some kotlin-js magic libraries I had a quick squiz at today but the solution is not guaranteed, and pretty sure non trivial, and would only work for kotlin (although for every platform)

Ok I?m getting the same logs now

Getting an error I?d expect in that the server is not ever called, but that?s because my trigger is empty

Is this the error I would expect from this Jsii issue?

My contract

Have got the test code on this branch if you want to check it out: https://github.com/dan-nichols/contract-case-kotlin/tree/test/add-client-contract

Potentially. The jsii error is that the mock server can?t respond

So the framework will continue if your trigger throws or returns

But not if it just waits

Hmm yeah the test might be waiting on a response

The error is a socket timeout so would make sense

Yep

Looks like you?ve done a nice job on the printing!

I indented some of it in the other implementations

But it?s hard to tell that without examples

I did a naive port of the java implementation

I want to use a different library that?s pure kotlin though, as the only jvm dependency (aside from Jsii boundary) is that ansii helper

Hmm. The Java impl should have the indenting but maybe I did it wrong

That style would actually look nice in Kotlin, though!

I do have indenting in the logger/printer but haven?t tested any of it so chances are it?s just broken

Well, it might be broken in the Java since I haven?t tested it either

I?m gonna work on the jsii bug tomorrow

@dan.nichols52 What do you need to get Kotlin Native working? C?

(or is it not Kotlin Native that you?re using?)

That DSL is really nice for Kotlin :raised_hands:

I think it?s C for kotlin Native

If using JSii, which I don?t think is actually supported

I can probably make another solution for C. Do you need it though?

Or are you using some other thing?

Also: Should the boundary expose the ANSI codes?

Eventually I think I?ll lean on cashapp?s Zipline for the kotlin DSL, which will let me run javascript from kotlin native code

I didn?t originally colour the strings, because I thought the host languages might not support the colours

Nice

In that case I?d actually stop using Jsii entirely tbh

You might be able to just modify the jest-dsl

just. use it for all kotlin targets

since it?s already a client of the case-boundary

and in JS

I?d hope to consume case-boundary from npm yeah>?

yes, but if you need to write JS for kotlin/js (I don?t know how it works), there?s already a fully written consumer of case-boundary

I need to do kotlin ?bindings? for javascript objects in kotlin-js, so I don?t think I get anything for free from jest dsl

Right, makes sense

?.would that approach also work for consuming it from Java?

:shrug: I almost didn?t bother tbh. How important is it for the logs to be colourful

Since nice to use is the top value, I?d say fairly

Yeah I?d be consuming the kotlin-js from kotlin-jvm

but it?s not more important than it ?. actually working

and having features

and the kotlin-js would be mapping/packaging javascript

All of this is not proven and would be very experimental

One of the next tasks is to automate the generation of the matcher documentation

The use-case for Zipline is to distribute kotlin code to mobile apps over the network

it?s pretty easy, it just needs to be done. The matchers are already in modules, so the approach would be to use `jsii-docgen` with the json output, parse that and either generate Markdown, or make a react component that can read the json.

So I?d essentially be using it without network

This sounds?. slightly more risky than my jsii plan, which ended up not quite working

but hey

It also sounds like the best approach, at least that I?m aware of

Yeah it?s risky but am planning to use it as an alternate to Jsii

If it works, I get all kotlin platforms supported

has joined #contract-case