Should this be LIFO or FIFO? 👀

The doc example doesn't read well to me, so I want FIFO.

   * @example
   * // Stack behaviors: first call returns `false`, subsequent calls return `true`
   * vi.when(spy)
   *   .calledWith('darkMode')
   *   .thenReturn(true)
   *   .thenReturnOnce(false)

So here you would consider thenReturnOnce to be unreachable?

You'd write it like this?

vi.when(spy)
  .calledWith('darkMode')
  .thenReturnOnce(false)
  .thenReturn(true)

I wonder what others think of this, as the fluent/builder APIs I've used were all LIFO-style, but the other mock APIs do seem to be FIFO.

Not sure, but from my limited english interpretation, the API suggest it should naturally read like:

when spy is called with x, then return y once, then return z (forever).

vi.when(spy)
  .calledWith(x)
  .thenReturnOnce(y)
  .thenReturn(z)

so current order seems inverted.

This is to be decided either by internal or public pole.

Is there a function that already retrieves the custom matchers and uses it?

I think we can just move it to utils/equals

I think it doesn't need to be experimental in v5

I think we can use _. The reason why ~ is usually chosen is because it's the last in the list of public APIs, but we have @internal flag which removes this method from the bundle, its types are only available in this repo

Can we just have a separate type instead of doing archeology in Behavior<unknown[], unknown>['actions'][number]?

Shouldn't it be 2 remaining (out of 2)?

What's the behavior of hanging calledWith without thenXxx? For example, I'm wondering if it's expected use case to only use calledWith to combine with toHaveBeenExhausted e.g.

const spy = vi.fn()
const w = vi.when(spy).calledWith(1)
expect(w).not.toHaveBeenExhausted()
spy(1)
expect(w).toHaveBeenExhausted()

It will use the provided fallback action/function. By default it would call the original spy implementation (which in this case is a noop).

There's indeed a bug with this, as the assertion would work even if it shouldn't. I wonder if it still makes sense for toHaveBeenExhausted to throw when there are no registered actions, as the check would be a bit more complex (checking that at least one behavior has an action) 🤔

I think throwing if there are no registered behaviours makes sense

The doc example doesn't read well to me, so I want FIFO.

   * @example
   * // Stack behaviors: first call returns `false`, subsequent calls return `true`
   * vi.when(spy)
   *   .calledWith('darkMode')
   *   .thenReturn(true)
   *   .thenReturnOnce(false)

I don't think you even need to care about negate if you use this.assert here instead of throwing an error

I have to triple check this tomorrow (examples were generated, have to check for API hallucinations).

I'm not even sure if it's a recipe or just a guide at this point, but I like the structure and that it's less abstract than what I've added previously.

I don't think we need the version here

Would be nice to also mention vi.when in "mocking functions" and just link here in the Learn section too (don't explain the API there for the sake of simplicity, just have a link at the bottom, I think - or a small mention in ::: tip)