feat: add mock call history to access request configuration in test #4029

blephy · 2025-01-25T09:58:49Z

This relates to...

Rationale

Actually we are not able with MockAgent to assert request configuration.

Given this in mind, the only way we could do it is by wrapping our app http call in function, and then spy or mock that function with our favorite test framework. We can make assertions on parameters we passed through that function but, even with this possibility, we are not certain that undici did not make computation on inputs.

This PR is addressing this problematic : ensuring http calls are made with the expected low level configuration, as far as we can.

Changes

add MockCallHistory and MockCallHistoryLog class
add getCallHistory class method to MockAgent instance
add clearCallHistory class method to MockAgent instance
add disableCallHistory class method to MockAgent instance
add enableCallHistory class method to MockAgent instance
add enableCallHistory MockAgent instantiation options
clear all call history logs when MockAgent.close is called

Features

Given this application :

function myCall(body: Record<string, unknown>, token: string) {
  await fetch(`https://my-service.io/endpoint`, {
      method: 'POST',
      body: JSON.stringify(body),
      headers: {
        authorization: 'Bearer ${token}',
        'content-type': 'application/json'
      }
  })
}

async function startApp(): Promise<void> {
  await myCall({ data: 'hello' }, 'myToken')
}

After :

describe('my app', () => {
  let agent: MockAgent

  before(() => {
    agent = new MockAgent({ enableCallHistory: true })
    setGlobalDispatcher(agent)
  })

  beforeEach(() => {
    agent.clearCallHistory()
  })

  after(async () => {
    await agent.close()
  })

  it('should request my external service with a specific body and headers', async () => {
    mockAgent.get('https://my-service.io').intercept({ path: '/endpoint', method: 'POST' }).reply(201, 'OK').times(1)

    await startApp()

    expect(mockAgent.getCallHistory()?.firstCall()?.body).toStrictEqual('"{ "data": "hello" }"')
    expect(mockAgent.getCallHistory()?.firstCall()?.headers['authorization']).toStrictEqual('Bearer myToken')
    expect(mockAgent.getCallHistory()?.firstCall()?.headers['content-type']).toStrictEqual('application/json')
    expect(mockAgent.getCallHistory()?.firstCall()?.path).toStrictEqual('/endpoint')
    expect(mockAgent.getCallHistory()?.firstCall()?.protocol).toStrictEqual('https:')
    expect(mockAgent.getCallHistory()?.calls()?.length).toStrictEqual(1)
  })

  it('should always call external services with a secure HTTP protocol', async () => {
    await startApp()

    // working without intercepting too

    expect(mockAgent.getCallHistory()?.filterCalls({ protocol: /^((?!https).)*$/ })?.length).toStrictEqual(0)
  })
})

Before :

describe('my app', () => {
  let agent: MockAgent

  before(() => {
    agent = new MockAgent({ enableCallHistory: true })
    setGlobalDispatcher(agent)
  })

  beforeEach(() => {
    agent.clearCallHistory()
  })

  after(async () => {
    await agent.close()
  })

  it('should request my external service with a specific body and headers', async () => {
    const spy = spyOn(myCall)
    mockAgent.get('https://my-service.io').intercept({ path: '/endpoint', method: 'POST' }).reply(201, 'OK').times(1)

    await startApp()

    expect(spy.calls?.[0]).toHaveBeenCalledWith({ data: 'hello' }, 'myToken')
    // we cannot do it, we must modify our application code and this will only assert function parameters, not the real http request
    // expect(mockAgent.getCallHistory()?.firstCall()?.headers['authorization']).toMatch(/^Bearer /)
    // we cannot do it, we must modify our application code and this will only assert function parameters, not the real http request
    // expect(mockAgent.getCallHistory()?.firstCall()?.headers['content-type']).toStrictEqual('application/json')
    // we cannot do it, we must modify our application code and this will only assert function parameters, not the real http request
    // expect(mockAgent.getCallHistory()?.firstCall()?.path).toStrictEqual('/endpoint')
    // we cannot do it, we must modify our application code and this will only assert function parameters, not the real http request
    // expect(mockAgent.getCallHistory()?.firstCall()?.protocol).toStrictEqual('https:')
    expect(spy.calls.length).toStrictEqual(1)
  })

  it('should always call external services with a secure HTTP protocol', async () => {
    await startApp()

    // we cannot do it, we must modify our application code and this will only assert function parameters, not the real http request
    // expect(mockAgent.getCallHistory()?.filterCalls({ protocol: /^((?!https).)*$/ })?.length).toStrictEqual(0)
  })
})

Status

metcoder95

Can you add testing for it?

lib/mock/mock-interceptor.js

blephy · 2025-01-26T10:54:38Z

Yes for sur. I just need times

mcollina

Thanks for opening a PR! Can you please add a unit test?

lib/mock/mock-call-history.js

test/mock-agent.js

types/index.d.ts

docs/docs/best-practices/mocking-request.md

lib/mock/mock-call-history.js

lib/mock/mock-interceptor.js

test/mock-agent.js

metcoder95

lgtm, small comment left

lib/mock/mock-call-history.js

metcoder95

LGTM, left minor comment and should be ready on my end

lib/mock/mock-agent.js

blephy · 2025-01-31T09:41:08Z

@mcollina can you take a bit of time to review back this PR ? it would be nice to have this change in the next release 🙏🏼

blephy · 2025-02-07T12:22:54Z

@mcollina 😢

mcollina

Thanks for doing this.

I'm also sorry it took so long for me to check out. I've been buried in work for the last few weeks.

I have question: why is the call history log a singleton? I don't think it should be.

blephy · 2025-02-17T08:21:16Z

Hi @mcollina !

I saw that, don't worry about, i looked at your work and maintaining all of this open source projects + a job is not an easy part ;)

To answer at your question :

MockCallHistoryLog is not a singleton. it contains information about one request configuration and is instantiable.
MockCallHistory is an hybride singleton. it contains every mock call history log for a particular set of requests. You can instantiate a MockCallHistory but at instantiation the instance is registered on a private static class method to be able to :
- clear every instante when needed
- delete every instante when needed
- retrieve an instance based on the name of the set of requests.

NB : the main purpose of the static class method is to avoid to register and associate an history instance to a MockAgent or a MockScope. In my own opinion, this is the most simple way to do it and the safer way to register multiple instance when constructing multiple MockAgent / MockScope withou having to forget to delete them.

mcollina · 2025-02-17T08:32:27Z

NB : the main purpose of the static class method is to avoid to register and associate an history instance to a MockAgent or a MockScope. In my own opinion, this is the most simple way to do it and the safer way to register multiple instance when constructing multiple MockAgent / MockScope withou having to forget to delete them.

Can you please remove it, and have it passed directly to MockAgent, or just create one in MockAgent if enabled? We already have one singleton (the default dispatcher), I don't want to have two to reset after each test.

blephy · 2025-02-17T09:18:58Z

Ok i will rollback to my previous implementation, but delete the ability to bind a mockCallHistory instance to a mockDispatch because without this static class method, i cannot get the mockCallHistory associated with a mockDispatch with mockAgent.getCallHistory(name) :

attach a MockCallHistory instance to a MockAgent instance if / when enabled
when mockAgent.close is called, the MockCallHistory instance associated with the mockAgent instance will be cleared (the option / instance will still be set for reuse)

WDYT @mcollina ?

ps : i can do it this night

mcollina · 2025-02-17T13:25:52Z

that should work

blephy · 2025-02-18T18:29:40Z

@mcollina this is done in this commit 0f6f62e

I also rebase on main and force pushed

blephy · 2025-03-03T09:53:36Z

@mcollina a little up :D

test/mock-agent.js

mcollina

lgtm

blephy · 2025-03-10T14:46:28Z

🎉 !

I let you merge guys

Thx for your time

* nodejs/main: (23 commits) Bumped v7.5.0 (nodejs#4091) Removed clients with unrecoverable errors from the Pool (nodejs#4088) feat: Allow disabling autoSelectFamily in an Agent (nodejs#4070) chore: update cache tests (nodejs#4027) fix: Fix retry-handler.js when retry-after header is a Date (nodejs#4084) feat: add mock call history to access request configuration in test (nodejs#4029) feat(docs): button to switch dark and light mode (nodejs#4044) Bumped v7.4.0 (nodejs#4071) fix: fix EnvHttpProxyAgent for the Node.js bundle (nodejs#4064) chore: update WPT (nodejs#4062) chore: update WPT (nodejs#4028) fix: handle missing vary header values (nodejs#4031) fix: do not throw unhandled exception when data is undefined in interceptor.reply (nodejs#4036) test: fix windows wpt (nodejs#4050) feat: mark `EnvHttpProxyAgent` as stable (nodejs#4049) don't check AbortSignal maxListeners on some node versions (nodejs#4045) feat(docs): copy to clipboard button (nodejs#4037) docs: fix incorrect method signature of `onResponseError` (nodejs#4030) docs: document about global dispatcher and errors (nodejs#3987) (nodejs#4014) chore: update WPT (nodejs#4011) ...

metcoder95 linked an issue Jan 26, 2025 that may be closed by this pull request

Mock history #4025

Closed

metcoder95 reviewed Jan 26, 2025

View reviewed changes

lib/mock/mock-interceptor.js Outdated Show resolved Hide resolved

mcollina requested changes Jan 26, 2025

View reviewed changes

lib/mock/mock-call-history.js Outdated Show resolved Hide resolved

blephy commented Jan 26, 2025

View reviewed changes

test/mock-agent.js Outdated Show resolved Hide resolved

blephy requested review from mcollina and metcoder95 January 27, 2025 00:28

blephy changed the title ~~feat: add mock call histories~~ feat: add mock call history Jan 27, 2025

blephy changed the title ~~feat: add mock call history~~ feat: add mock call history to access request configuration in test Jan 27, 2025

blephy commented Jan 27, 2025

View reviewed changes

types/index.d.ts Outdated Show resolved Hide resolved

metcoder95 reviewed Jan 28, 2025

View reviewed changes

github-advanced-security bot found potential problems Jan 28, 2025

View reviewed changes

test/mock-agent.js Fixed Show fixed Hide fixed

test/mock-agent.js Fixed Show fixed Hide fixed

test/mock-agent.js Fixed Show fixed Hide fixed

test/mock-agent.js Fixed Show fixed Hide fixed

blephy requested a review from metcoder95 January 28, 2025 19:26

metcoder95 approved these changes Jan 29, 2025

View reviewed changes

lib/mock/mock-call-history.js Show resolved Hide resolved

blephy requested a review from metcoder95 January 29, 2025 18:20

metcoder95 reviewed Jan 30, 2025

View reviewed changes

lib/mock/mock-agent.js Outdated Show resolved Hide resolved

blephy requested a review from metcoder95 January 30, 2025 11:27

metcoder95 approved these changes Jan 31, 2025

View reviewed changes

blephy force-pushed the add-mock-history branch from d567704 to 437eeee Compare February 14, 2025 00:01

mcollina reviewed Feb 16, 2025

View reviewed changes

blephy added 4 commits February 18, 2025 19:28

feat: add mock call histories

51f9e36

test: add mock call history specs

550156d

chore: resolve discussion

f4a1bb7

chore: own review

a9b69a6

blephy added 11 commits February 18, 2025 19:28

fix: CodeQL sniffing

6f43a40

chore: own review

3d1f629

feat: add AND and OR operator to filterCalls class method

b948584

chore: own review

05ef5e1

fix: ts types

d5fb5b9

fix: ts types

1b30b4c

docs: fix url in documentation website

0c25ad1

feat: make MockCallHistory iterable

6f4b53d

fix: throw if enableCallHistory is not a boolean

9a67df4

fix: ts type definitions and specs

7b44e26

test: fix tsd tests

ee7c292

blephy force-pushed the add-mock-history branch from 437eeee to 78892ff Compare February 18, 2025 18:28

chore: resolve discussion

0f6f62e

blephy force-pushed the add-mock-history branch from 78892ff to 0f6f62e Compare February 18, 2025 18:39

blephy requested a review from mcollina February 18, 2025 20:35

metcoder95 approved these changes Feb 19, 2025

View reviewed changes

github-advanced-security bot found potential problems Mar 3, 2025

View reviewed changes

test/mock-agent.js Dismissed Show dismissed Hide dismissed

Merge branch 'main' into add-mock-history

7320f6f

mcollina approved these changes Mar 9, 2025

View reviewed changes

metcoder95 merged commit 6179788 into nodejs:main Mar 10, 2025
28 of 31 checks passed

This was referenced Mar 12, 2025

[Release] v7.4.1 #4090

Closed

[Release] v7.5.0 #4091

Merged

[Release] v6.21.2 #4092

Closed

github-actions bot mentioned this pull request May 12, 2025

[Release] v6.21.3 #4211

Closed

Uh oh!

feat: add mock call history to access request configuration in test #4029

feat: add mock call history to access request configuration in test #4029

Uh oh!

Conversation

blephy commented Jan 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

This relates to...

Rationale

Changes

Features

Status

Uh oh!

metcoder95 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

blephy commented Jan 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mcollina left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

metcoder95 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

metcoder95 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

blephy commented Jan 31, 2025

Uh oh!

blephy commented Feb 7, 2025

Uh oh!

mcollina left a comment

Choose a reason for hiding this comment

Uh oh!

blephy commented Feb 17, 2025

Uh oh!

mcollina commented Feb 17, 2025

Uh oh!

blephy commented Feb 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mcollina commented Feb 17, 2025

Uh oh!

blephy commented Feb 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

blephy commented Mar 3, 2025

Uh oh!

Uh oh!

mcollina left a comment

Choose a reason for hiding this comment

Uh oh!

blephy commented Mar 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

blephy commented Jan 25, 2025 •

edited

Loading

blephy commented Jan 26, 2025 •

edited

Loading

blephy commented Feb 17, 2025 •

edited

Loading

blephy commented Feb 18, 2025 •

edited

Loading

blephy commented Mar 10, 2025 •

edited

Loading