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

**URL:** <https://racket.discourse.group/t/difference-between-fail-and-fail-check/506>\
**Category:** Questions & Answers\
**Tags:** question, rackunit\
**Created:** [January 1, 2022, 5:14pm UTC](https://racket.discourse.group/t/difference-between-fail-and-fail-check/506 "2022-01-01T17:14:20Z")\
**Posts on this page:** 6\
**Page:** 1

<div class="post-metadata">

**Author:** ![sschwarzer](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/sschwarzer/32/1940_2.png) [@sschwarzer](https://racket.discourse.group/u/sschwarzer)\
**Post date:** [January 1, 2022, 5:14pm UTC](https://racket.discourse.group/t/difference-between-fail-and-fail-check/506/1 "2022-01-01T17:14:20Z")

</div>

Happy New Year everyone! 🙂

* * *

The [rackunit documentation](https://docs.racket-lang.org/rackunit/index.html) describes two functions:

- [fail](https://docs.racket-lang.org/rackunit/api.html#%28def._%28%28lib._rackunit%2Fmain..rkt%29._fail%29%29)
- [fail-check](https://docs.racket-lang.org/rackunit/api.html#%28def._%28%28lib._rackunit%2Fmain..rkt%29._fail-check%29%29)

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

I have used `fail` in several test cases in patterns like

```scheme
(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. 🙂 )

---

<div class="post-metadata">

**Author:** ![sorawee](https://avatars.discourse-cdn.com/v4/letter/s/ea5d25/32.png) [@sorawee](https://racket.discourse.group/u/sorawee)\
**Post date:** [January 2, 2022, 12:18am UTC](https://racket.discourse.group/t/difference-between-fail-and-fail-check/506/2 "2022-01-02T00:18:38Z")

</div>

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

```scheme
#lang racket
(require rackunit)
(fail)

```

you will get a nice test report:

```scheme
--------------------
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:

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

```

an exception is thrown, which is uncaught:

```scheme
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`.

---

<div class="post-metadata">

**Author:** ![sorawee](https://avatars.discourse-cdn.com/v4/letter/s/ea5d25/32.png) [@sorawee](https://racket.discourse.group/u/sorawee)\
**Post date:** [January 2, 2022, 6:42pm UTC](https://racket.discourse.group/t/difference-between-fail-and-fail-check/506/3 "2022-01-02T18:42:44Z")

</div>

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):

```scheme
pre-content
@--------------------
post-content

```

```scheme
pre-content
```

---

<div class="post-metadata">

**Author:** ![sschwarzer](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/sschwarzer/32/1940_2.png) [@sschwarzer](https://racket.discourse.group/u/sschwarzer)\
**Post date:** [January 2, 2022, 10:03pm UTC](https://racket.discourse.group/t/difference-between-fail-and-fail-check/506/4 "2022-01-02T22:03:42Z")

</div>

So my understanding is:

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

Is this correct?

---

<div class="post-metadata">

**Author:** ![sorawee](https://avatars.discourse-cdn.com/v4/letter/s/ea5d25/32.png) [@sorawee](https://racket.discourse.group/u/sorawee)\
**Post date:** [January 2, 2022, 10:21pm UTC](https://racket.discourse.group/t/difference-between-fail-and-fail-check/506/5 "2022-01-02T22:21:45Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![sschwarzer](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/sschwarzer/32/1940_2.png) [@sschwarzer](https://racket.discourse.group/u/sschwarzer)\
**Post date:** [January 2, 2022, 11:20pm UTC](https://racket.discourse.group/t/difference-between-fail-and-fail-check/506/6 "2022-01-02T23:20:51Z")

</div>

> [@sorawee](#):
>
> So that’s how it’s intended to be used.

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