feat(fromOpenApi): support mapping and filtering operations #57

jauniusmentimeter · 2024-07-17T12:15:16Z

Add possibility to filter open api spec spec and not mock the whole spec.

The reason for introducing this is that it's quite common case that one has open api spec with lots of endpoint definitions, but for a specific tests we want to mock just specific endpoints. Due to that, it's good to be possible to do filtering on both url and method.

kettanaito · 2024-07-17T12:40:16Z

src/open-api/from-open-api.ts

@@ -11,6 +11,12 @@ const supportedHttpMethods = Object.keys(
  http,
 ) as unknown as SupportedHttpMethods

+export type MapOperationFunction = (
+  url: string,


I recommend using object-as-argument pattern:

export type X = (args: { url: string, method: Y, operation: Z }) => T

We should've done that in fromTraffic too, and that's something I'd like to do in the future versions.

I am curious if we want to pass the PathItemObject instead and then let the user return the responses it wants to map?

@weyert, I'm not sure whether that's beneficial. We may think more about how to decide which responses from the spec to pick. Right now, the library recommends using a search parameter but that means modifying the system's behavior, which I don't like.

You can use this map function instead... I'm thinking if that has any complications. For once, if you drastically transform the spec, you won't be able to know what is actually the source of truth for the network. It kind of becomes your map function, which is bad.

It would be great to rely on something like response scenarios name/ids. So you cannot modify them, maintaining the source of truth, but can reference/swap per your need.

changed to object argument: c49d3c7

@kettanaito Sorry, what do you mean with system's behaviour? Some other mocking solutions allow you to set a HTTP header to define which example of the responses should be returned.

@weyert, I meant the server you are describing in your OAS document. Basically, my main argument is to support filtering primarily, since the more your runtime modifies your spec, the least useful your spec becomes. If you need to modify an operation in your spec, that's an indicator your spec isn't covering all use cases (otherwise, why would you want to modify it?) I'd rather recommend developers extend their specs to cover the scenarios they want, and have Source provide them with the means to target specific scenarios in test (like we have with triggering particular response examples by the status code search parameter).

That's true. The idea of this PR is to limit the number of endpoints get mocked. If you have a specification with hundreds of endpoints then you might not need to mock all of them. So I like that the idea of this PR to only mock a subset of the endpoints. As you said I can also imagine that you might want to only mock a particular response example of an endpoint. Both are valid use cases but I agree with you that just remapping endpoints shouldn't be an end goal here.

But I do agree that it would be nice to cherry-pick certain responses (see #55).

kettanaito · 2024-07-17T12:43:06Z

src/open-api/from-open-api.ts

+      }
+
+      const operation = mapOperation
+        ? mapOperation(url, method, rowOperation)


I think this is properly referred to as path, not url, is it? We may consider renaming it across the implementation, including the new map function.

yea path is the open api spec concept. Renamed in the mapper function and also other places that touch open api spec:

c642e1f
ef583e7

If I missed url to path renaming somewhere else, let me know. I did not touch places such as isAbsoluteUrl since that one has to do with url as per my understanding and not the open api spec path concept

src/open-api/from-open-api.ts

kettanaito · 2024-07-17T12:55:32Z

src/open-api/from-open-api.ts

@@ -11,6 +11,12 @@ const supportedHttpMethods = Object.keys(
  http,
 ) as unknown as SupportedHttpMethods

+export type MapOperationFunction = (
+  url: string,


Let's expose the whole parsed document of the spec as well. That way, developers can access any information anywhere to help them filter or map operations.

test/oas/from-open-api.test.ts

kettanaito · 2024-07-17T12:56:25Z

test/oas/from-open-api.test.ts

+  }
+  const handlers = await fromOpenApi(openApiSpec, mapOperation)
+
+  expect(await inspectHandlers(handlers)).toEqual<InspectedHandler[]>([


We need to add the request test for /orders too, since now nothing will fail if the GET /orders operation gets request handlers generated.

hmm it will fail, no? Since toEqual will actually check the whole structure of actual vs expected. So if GET /orders gets generated, the handlers will contain not one handler anymore and the expect will not pass.

I added an extra expect for that to check the handlers length anyway: e3d2391

kettanaito · 2024-07-17T12:57:46Z

test/oas/from-open-api.test.ts

+import { createOpenApiSpec } from '../support/create-open-api-spec.js'
+import { InspectedHandler, inspectHandlers } from '../support/inspect.js'
+
+it('creates handlers based on provided filter', async () => {


Let's add another test case for mapping the operation. It may look like this:

OAS with 1 operation defined.

In the map function, we modify something about the operation (e.g. its path).

The rest of the test as usual (request -> assertion).

That's a great test! 45df894
I modified response, since operation itself does not contain path and that one we are not able to modify in this mapping function

jauniusmentimeter · 2024-07-18T09:50:27Z

@kettanaito @weyert these new commits improve types for mapper function, so please re-review:
898c443
a214ae2

Path in the mapper function will now be union of real paths instead of being just string

weyert · 2024-07-26T19:28:23Z

@kettanaito @weyert these new commits improve types for mapper function, so please re-review: 898c443 a214ae2

Path in the mapper function will now be union of real paths instead of being just string

Looks good. Not sure why all those description fields needs to be added, though

kettanaito · 2024-07-30T14:47:58Z

This looks extremely good, @jauniusmentimeter! ❤️ Thank you so much for your hard work here. I skimmed through the discussions, and most seem to be resolved. Please let me also test this locally sometime this week, hopefully. Would love to get this merged.

jauniusmentimeter added 4 commits July 17, 2024 13:36

feat(fromOpenApi): add possibility to filter oas

14abf27

refactor(fromOpenApi): make mapper function accept 3 arguments

e1674fb

refactor(fromOpenApi): change variable name to more descriptive one

ef6531c

style(fromOpenApi): remove unneeded empty line

b3b644a

kettanaito reviewed Jul 17, 2024

View reviewed changes

src/open-api/from-open-api.ts Outdated Show resolved Hide resolved

refactor(fromOpenApi): use object-as-argument for mapper function

c49d3c7

kettanaito reviewed Jul 17, 2024

View reviewed changes

test/oas/from-open-api.test.ts Outdated Show resolved Hide resolved

kettanaito reviewed Jul 17, 2024

View reviewed changes

kettanaito changed the title ~~Add possibility to filter oas~~ feat(fromOpenApi): support mapping and filtering operations Jul 17, 2024

kettanaito reviewed Jul 17, 2024

View reviewed changes

jauniusmentimeter added 8 commits July 17, 2024 15:10

refactor(fromOpenApi): rename url to path

c642e1f

refactor(fromOpenApi): rowOperation -> rawOperation

b73aa7b

refactor(fromOpenApi): expose open api document to mapper function

e6a83f2

test(fromOpenApi): inline mapper function

89f2e80

test(fromOpenApi): expect one handler to be generated

e3d2391

test(fromOpenApi): add test for when mapper modifies operation

45df894

feat(fromOpenApi): rename parameter from url to path

ef583e7

feat(fromOpenApi): improve typings

898c443

jauniusmentimeter added 2 commits July 18, 2024 11:52

refactor(fromOpenApi): make generic singular

a214ae2

refactor(fromOpenApi): extract common type to a separate

053d58b

kettanaito mentioned this pull request Aug 1, 2024

Another way to condition a response #55

Open

Merge branch 'main' into add-possibility-to-filter-oas

f31ae1b

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(fromOpenApi): support mapping and filtering operations #57

feat(fromOpenApi): support mapping and filtering operations #57

jauniusmentimeter commented Jul 17, 2024

kettanaito Jul 17, 2024

weyert Jul 17, 2024

kettanaito Jul 17, 2024

kettanaito Jul 17, 2024

jauniusmentimeter Jul 17, 2024

weyert Jul 17, 2024

kettanaito Jul 30, 2024

weyert Jul 30, 2024

kettanaito Aug 1, 2024

kettanaito Jul 17, 2024

jauniusmentimeter Jul 17, 2024 •

edited

Loading

kettanaito Jul 17, 2024

jauniusmentimeter Jul 17, 2024

kettanaito Jul 17, 2024

jauniusmentimeter Jul 17, 2024 •

edited

Loading

kettanaito Jul 17, 2024

jauniusmentimeter Jul 17, 2024

jauniusmentimeter commented Jul 18, 2024 •

edited

Loading

weyert commented Jul 26, 2024

kettanaito commented Jul 30, 2024

feat(fromOpenApi): support mapping and filtering operations #57

Are you sure you want to change the base?

feat(fromOpenApi): support mapping and filtering operations #57

Conversation

jauniusmentimeter commented Jul 17, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jauniusmentimeter Jul 17, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jauniusmentimeter Jul 17, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jauniusmentimeter commented Jul 18, 2024 • edited Loading

weyert commented Jul 26, 2024

kettanaito commented Jul 30, 2024

jauniusmentimeter Jul 17, 2024 •

edited

Loading

jauniusmentimeter Jul 17, 2024 •

edited

Loading

jauniusmentimeter commented Jul 18, 2024 •

edited

Loading