jest: [jest-circus] missing fail() method

As a result of this issue, there is currently a discrepancy between @types/jest, which does define fail, and jest-circus, which does not define fail. Discussion in DefinitelyTyped

As a temporary workaround, you can define your own fail function:

function fail(reason = "fail was called in a test.") {
  throw new Error(reason);
}

global.fail = fail;

Hi! How this incredibly stupid bug could still be present after a so long time?! I’ve never seen a test framework without a fail() method in my whole life. This not fixed regression after 2 years is a huge embarrassment for jest and a huge lack of serious.

Any update on this? Many of my integration tests are missing the correct messaging now that this is undefined, and its causing a lot of confusion.

As a result of this issue, there is currently a discrepancy between @types/jest, which does define fail, and jest-circus, which does not define fail. Discussion in DefinitelyTyped

As a temporary workaround, you can define your own fail function:

function fail(reason = "fail was called in a test.") {
  throw new Error(reason);
}

global.fail = fail;

Unfortunately that’s not equivalent. The problem I’m having is that I need to fail a test from a location where any throw will be caught. Is there any more equivalent option available?

Any chance this will be fixed in any new release?

Using the answer proposed here I tested if the same behavior could be applied to Jest. My theory was correct. It is possible to fail a Jest test if you call the done callback function with some param. Here an example:

    test('this test must fail', (done) => {
        done('hey Rainyel this is a failed test')
    });

Output:

● this test must fail

Failed: "hey Rainyel this is a failed test"

   6 |
   7 | test('this test must fail', (done) => {
>  8 |   done('hey Rainyel this is a failed test')
     |   ^
   9 |
  10 | });
  11 |

  at Object.<anonymous> (src/__tests__/test.super.ts:8:3)

Any update on this?

Or at least some information as to:

• Why this feature has been removed
• How can we achieve what we used to achieve with fail

Same here! Would love to have this issue alleviated sooner than later 😃

Same here, too. No change after fix

Same here

Hi, just wanted to share the workaround I’m using. I have created a fail function using expect and a failing comparison. It also displays messages in an okayish way. It’s not the cleanest solution, but it solves the problem mentioned here. Maybe it is helpful for someone.

function fail(message = "") {
    let failMessage = "";
    failMessage += "\n";
    failMessage += "FAIL FUNCTION TRIGGERED\n";
    failMessage += "The fail function has been triggered";
    failMessage += message ? " with message:" : "";

    expect(message).toEqual(failMessage);
}

Don’t take me wrong, but they don’t owe you or us anything. The developers have their own lives, with their own problems and need to pay their bills at the end of the month too. If you really need this, you can use your spare time (like they do when they develop jest) and submit a PR to fix this issue.

This is still happening in 29.5.0

Hell… I’ve just arrived here to find a regression from >2.5 years ago and it’s full of workarounds.

Will someone either close this as won’t fix or fix it!

Or just move to another testing framework. I moved one project to vitest (Jest api compatible) this week, and noticed there was an expect.fail function.

That’s what I will do now: by letting this shit for a so long time, they completely discredited themselves and showed their total lack of seriousness. I will replace jest by another framework for my current and next projects for all the companies, and hardly advise to everybody to never choose that framework for their tests. I already do the same with TypeOrm which proved its total lack of seriousness too about the non fixed regressions and bugs.

Or just move to another testing framework. I moved one project to vitest (Jest api compatible) this week, and noticed there was an expect.fail function.

After spending a few more hours on the problem this morning, I found a satisfactory solution using a custom matcher which builds off of the fail() matcher from jest-extended.

Use a Custom Matcher (works in try/catch blocks)

function toFail(_, message) {
  this.dontThrow();  // <-- Enables recording failures in try/catch blocks
  return {
    pass: false,
    message: () => (message ? message : 'fails by .toFail() assertion'),
  };
}

expect.extend({ toFail });

// FUNCTION UNDER TEST
function invokeWithTry(callback) {
  try {
    return callback();
  } catch (err) {
    return err;
  }
}

// SETUP THE CUSTOM MATCHER
function toFail(_, message) {
  this.dontThrow();  // Just record the error when a test fails, no error throwing
  return {
    pass: false,
    message: () => (message ? message : 'fails by .toFail() assertion'),
  };
}

expect.extend({ toFail });

// TESTS
test("fail works in a try/catch", () => {
  expect().not.toFail("unexpected failure"); // Correctly passes
  const result = invokeWithTry(() => expect().toFail("expected failure")); // Correctly fails
  expect(result).toBeUndefined(); // Correctly passes
});

I just saw @atz3n’s workaround and decided to simplify it…

Write a custom fail function

function fail(message: string = '') {
  expect(`[FAIL] ${message}`.trim()).toBeFalsy();
}

Full example Note This workaround is still inferior to the original fail

1. The original fail was automatically globally available.
2. In failure messages, code snippets showed the invocation of the original fail. This workaround shows the expect call in its implementation.

There are already simple work-arounds like this in the thread above. There’s also another way you’ve missed that it’s inferior to the original fail: it simply doesn’t work if it’s executed within a callback where a parent performs a catch. E.g.:

function underTest(callback) {
  try {
    return callback();
  } catch (error) {
    return false;
  }
}

In cases like this any fail() call in callback will be silently ignored and the test still passes because all it does it throw an exception anyone can catch rather than actually mark the test as failed. That’s a pretty big drawback.

@vtgn: maybe because there are bigger and older issues with Jest, like #6695.

also running into this while trying to upgrade from jest 26 to jest 27…

ReferenceError: fail is not defined

I just ran into a test where I was getting “fail() is undefined” and had assumed all this time that fail worked like it used to since it exists in @types/jest.

Just to clarify why this functionality is important:

it('should fail if the document does not exist.', async () => {
      await c.accessor.delete();

      const exists = await c.accessor.exists();
      expect(exists).toBe(false);

      try {
        await c.accessor.update(c.dataForUpdate());  // should not succeed
        fail();   // previously this would signal to Jest to properly end the test as a failure, but not get caught in the below.
      } catch (e) {
        expect(e).toBeDefined(); // expect an error occured
      }
});

The above code with Jest 28 will now incorrectly always succeed, as fail() throw an exception that gets caught by the catch.

We don’t want to catch any error either though, as unexpected errors should result in a test failure rather than success. We just want the tests to succeed when failures are expect.

I went ahead and created some test utility functions so I can continue using this pattern. I did end up finding and resolving a few more bugs too. Now the example test looks like:

    import { itShouldFail, expectFail } from '@dereekb/util/test';
    
    ...

    itShouldFail('if the document does not exist.', async () => {
      await c.accessor.delete();

      const exists = await c.accessor.exists();
      expect(exists).toBe(false);

      await expectFail(() => c.accessor.update(c.dataForUpdate()));
    });

It will be published on npm with @dereekb/util@^8.1.0.

I’m not too familiar with the inner workings of Jest or why it dropped the previous functionality of fail(), but I imagine it could be brought back for the cases where we are looking for a specific error. Jest’s it functionality could be extended with a function that looks for failures, (I.E. it.fail, or something) and then watch for a specific exception to be thrown that is thrown by failSuccessfully() or something to that manner. Someone more familiar with building Jest extensions may see a better way to implement it as an extension as well.