Difference between `fail` and `fail-check`?

Questions & Answers
,
#1

Happy New Year everyone! :slight_smile:

The rackunit documentation describes two functions:

From the descriptions both functions seem very similar, - so similar that I'm not sure when I should use which. :wink:

I have used fail in several test cases in patterns like

(unless some-condition
  (fail "some message"))

and everything seems to work fine.

Are there situations when I should use fail-check instead (for example in define-check?), and if yes, why wouldn't fail work there?

(Whatever the answers to my questions are going to be, I wish someone would clarify the use of fail vs. fail-check in the documentation. :slight_smile: )

1 Like
#2

fail is a kind of check. That means if you write:

#lang racket
(require rackunit)
(fail)

you will get a nice test report:

--------------------
FAILURE
name:       fail
location: ...
params:     '()
--------------------

fail-check is meant to be used in define-check. If you use it at the
top-level / module-level:

#lang racket
(require rackunit)
(fail-check "abc")

an exception is thrown, which is uncaught:

abc
  context...:
    ...

Does using fail instead of fail-check work? It appears to, but that's
mostly a coincidence for this implementation. You can imagine a different
RackUnit implementation where this is not the case, so you should avoid it.

I think that mentioning define-check in the fail-check documentation is a
good idea, since they should be cooperating with each other. Note that
define-check already mentions fail-check.

1 Like
#3

Thanks to @sschwarzer for letting me know my message was incorrectly processed by Discourse. I fixed the above reply. It appears Discourse will remove any content after a horizontal line when posted from email. Let’s see if this is true (sorry for a bit off-topic):

pre-content
@--------------------
post-content


pre-content
#4

So my understanding is:

  • Use fail-check inside define-check and similar forms.
  • Otherwise use fail.

Is this correct?

#5

Well, definitely use fail-check inside define-check.

The documentation of fail states:

Good for creating test stubs that you intend to fill out later.

So that’s how it’s intended to be used.

#6

I read this, but I think mentioning that it's useful for stubs doesn't automatically say that this is the only use. :thinking: So this is still a bit vague in my opinion.