My first reaction was to think "we throw a warning when verifying invocations that are also stubbed" and indeed, when changed to td.verify(API.run('should fail')) (without await) is invoked, that warning is printed:

Warning: testdouble.js - td.verify - test double `run` was both stubbed and verified with arguments ("should fail"), which is redundant and probably unnecessary. (see: https://github.com/testdouble/testdouble.js/blob/main/docs/B-frequently-asked-questions.md#why-shouldnt-i-call-both-tdwhen-and-tdverify-for-a-single-interaction-with-a-test-double )

It also prints the failure:

result fail

And the uncaught promise error:

[UnhandledPromiseRejection: This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). The promise rejected with the reason "fail".] {
  code: 'ERR_UNHANDLED_REJECTION'
}

Here's my REPLit fork to verify that. Am I missing something here?

I guess I'm confused about the uncaught promise error. It seems to me like runSafely handles the rejected promise from API.run(). Since test is executing successfully and logging its result in .then(), so I would assume there would be no unhandled rejections.

But the top level unhandled rejection seems to break my test suite ☹️ In the repl you shared, I interpret the exit status 1 as a sign that the test suite is failing (and this matches the behavior in my mocha tests).

Does that help? Can I provide any more info? 😀

I found that I can fix my tests by explicitly catching the error generated by this verify call.

  td.verify(
    API.run('should fail').catch(err => null)
  ) 

This will still fail the test if API.run does not get called as expected, but stops the rejection call from failing the test. It seems a little surprising / magic to have this scattered throughout my test code though 😅

Yes, this is happening to you as a side effect of stubbing what you're verifying. First the test stubs td.when(API.run('should fail')).thenReject('fail'), but that means the subsequent demonstration of that call inside the td.verify() that satisfies the stubbing will also return a rejected promise, which in turn Node will detect as being uncaught/unhandled.

The real solution IMO is to address the td.js warning and not stub what you're also verifying, by instead adding a normal assertion that indirectly demands the stubbing be used as expected. This is how I would change it:

td.replace(API, 'run')
td.when(API.run('should fail')).thenReject('fail')

async function test(): Promise<string> {
  const value = await runSafely('should fail')

  assert.strictEqual(value, 'fail')
  return value
}

test()
  .then(result => console.log('result', result))
  .catch(err => console.log('error', err))