How to test endpoints using Jest

[Isaac-Leonard]

Given that express-zod-api is currently able to generate swagger documentation would it be possible to add test-data generation too or even full jest test generation?
not as a replacement for tests but as a way to remove the majority of the boilerplate usually required when writing tests for express controllers.
I'm happy to write the code for this myself if needed.

[RobinTail]

That's an interesting idea, @Isaac-Leonard. Perhaps there should be a property within the .build() method of EndpointsFactory... something like

defaultEndpointsFactory.build({
  // ...,
  tests: [
    { request: {}, expectedResponse: {} }
  ]
})

I need to think a little bit more on it.
Please let me know if you have any suggestions on how this feature could be implemented.

[Isaac-Leonard]

I was more thinking of integrating with something like
https://github.com/anatine/zod-plugins/tree/main/libs/zod-mock
or
https://github.com/dipasqualew/zod-mocking
So that input test data could be generated automatically although I'm not sure what the best way to use it would be?
Like would it be generated once from a console script or something more stable?

[Isaac-Leonard]

Perhaps a good start would be to simply expose the handler function on the Endpoint object after building it so it can be imported and called from test scripts without needing to provide full mockups of request and response objects.

[Isaac-Leonard]

I made a pull request where I've added a method to the endpoint class that runs the handler with a provided input and optional logger for use by tests
#229
I don't think its fully ready yet but I also added a passing test for it so it should work for basic use-cases.

[Isaac-Leonard]

It might just be better to remove the protected modifier from the handler property though now that I think about it more.

[RobinTail]

Thank you @Isaac-Leonard , I will check out your PR
👍🏽

[RobinTail]

Thank you for your PR @Isaac-Leonard , your contribution and ideas are highly appreciated.
I realized that I need to clarify in the documentation on how to test endpoints.

Unfortunately I can not accept the offered solution due to the imbalance of efforts in relation to benefits.
The reason is that the offered method tests the output of the endpoint's handler, instead of its actual response, but more importantly — overlooking the error handling implemented in the ResultHandler that is part of the Endpoint's workflow.

The handler may throw an error, but how exactly it will affect on the Endpoint — decides the ResultHandler, which may be customized by design as well.

Therefore, testing handler is not enough. What should be tested is the public execute() method of Endpoint.
And there is no need for additional methods, since it is public.

So, how to test endpoints.

1. Mock request, response and logger
2. Invoke .execute({request, response, config, logger})
3. Assert expectations on response and/or logger methods.

Here is an example:

const requestMock = {
  method: "POST",
  header: jest.fn(() => "application/json"),
  body: {...},
};
const responseMock: Record<string, jest.Mock> = {
  set: jest.fn(() => responseMock),
  status: jest.fn(() => responseMock),
  json: jest.fn(() => responseMock),
};
const configMock = {
  cors: true, // or your actual config
};
await endpoint.execute({
  request: requestMock as unknown as Request,
  response: responseMock as unknown as Response,
  config: configMock as CommonConfig,
  logger: loggerMock,
});

expect(loggerMock.error).toBeCalledTimes(0);
expect(responseMock.status).toBeCalledWith(200);
expect(responseMock.json).toBeCalledWith({
  status: "success",
  data: {...},
});

That's it.
I hope you'll find this helpful, and I'm going increase the visibility of this information.

Thank you once again for your contribution!

P.S. Perhaps I will provide some sort of shorthand for mocking required entities, so it would take less efforts and be more obvious.

[Isaac-Leonard]

Sorry that I've been leaving issues by the way.
Would it be possible to remove the protected modifier from the handler method on the endpoint class to allow for unit testing just the handler without having to set up mocks for the requests and responses?

[RobinTail]

Hello @Isaac-Leonard ,

I've got a better idea.
I'm going to add a method that helps you to set up mocks.
I'm currently working on it within this PR: #252 .
The expected usage would look the following way:

const { responseMock, loggerMock } = await testEndpoint({
  endpoint,
  requestProps: {
    method: "POST",
    body: {...},
  },
});
expect(loggerMock.error).toBeCalledTimes(0);
expect(responseMock.status).toBeCalledWith(200);
expect(responseMock.json).toBeCalledWith({
  status: "success",
  data: {...},
});

[Isaac-Leonard]

That looks really good

[RobinTail]

The feature has been released in version 5.1.0 🚀

[RobinTail]

As of version 5.1.0 use the testEndpoint() method
https://github.com/RobinTail/express-zod-api/blob/master/CHANGELOG.md#v510-beta1