Testing Routes and Controllers: explicitly state that jest is required to test sample code

[hbar1st]

Checks

• This is not a duplicate of an existing issue (please have a look through our open issues list to make sure)
• I have thoroughly read and understand The Odin Project Contributing Guide
• Would you like to work on this issue?

Describe your suggestion

This lesson described supertest without actually differentiating clearly between it and testing frameworks like Jest/Mocha etc. An unsuspecting learner like me, reads the text of the lesson and doesn't realise that supertest doesn't work the same as these testing frameworks. The lesson doesn't actually also say that in order to run the supertest code samples given, we need a testing framework (Jest) to be installed and setup first.
This led me to make a couple of mistakes when trying out the lesson.
1- I didn't know that Supertest was not able to actually run the tests
2- Once I clarified on discord that I needed a test framework, I thought I should make use of vitest with the sample code (but that sample code doesn't actually work with vitest as you cannot use done with vitest).

Perhaps most of this would have been avoided if I'd had more experience with testing, but I'm not sure many of us do.
It was remarked on discord that this question (of how to run the sample code in the lesson) has come up before. I confirmed this.

An addition of a sentence to this lesson to mention the need for a test framework to use with Supertest and to instruct that Jest is required for the sample code would be helpful and appreciated.

thank you for your attention

Path

Node / JS

Lesson Url

https://www.theodinproject.com/lessons/nodejs-testing-routes-and-controllers

(Optional) Discord Name

hana-banana

(Optional) Additional Comments

No response

[ManonLef]

@hbar1st thanks for bringing this up!

The lesson states the following:

To facilitate actually testing these routes we’re going to use a library called SuperTest, so go ahead and npm install supertest --save-dev and while it’s installing take a few minutes to look through the readme on their git repo (linked above).

When I go through the readme as stated in the lesson, it mentions:

supertest works with any test framework, here is an example without using any test framework at all:

So I agree that the requirement to actually install and configure a testing framework could be emphasized more clearly in our steps, rather than just implied by reading the docs.

However, I can see how our example will not work with Vitest because it's written using "done" callback style instead of async/await.

I think it could be emphasised that we should not only read through the docs, but also set up our testing library of preference as stated in the readme of Supertest. And perhaps add that other testing libraries besides Jest might require a bit of refactoring of our code examples to work. Limiting it to Jest is not needed in my opinion, but the addition of a caution regarding the need to refactor might be. Probably somewhere in the following lesson excerpt:

In the examples below we’re going to use SuperTest inside of a Jest style describe/test block, but the syntax and use of these are common among most testing libraries, so the concepts should be easily replicated in Mocha with Chai or Jasmine or Tape or whatever testing library you prefer.

which gives learners the freedom to replicate the examples in another testing library if they so prefer. We already make it clear in the lesson we use Jest, but adding the caution here about the need for refactoring might be needed.

So basically I propose:

• emphasise the need to add a testing library if you want to code along with our examples
• in the section I quoted above, add a caution note that while most libraries share similar concepts, code examples using callbacks might require more refactoring for frameworks like Vitest.

This did make me consider if we should step back from the callback examples and moving our own examples away from the done() callback pattern entirely and adopting the modern async/await approach ourselves, making them more compatible with a wider range of modern testing setups by default. But I'd like more opinions on this from the @TheOdinProject/maintainers more well versed in NodeJs Testing.

[hbar1st]

Thanks for the analysis, however:
You said earlier:

We already make it clear in the lesson we use Jest,

I disagree with this. I am not the only who didn't know that "jest style" was === "jest". I thought the statement was just saying that the code "looked like" jest. I didn't even understand that we were supposed to use a test runner at all!
I'd be happy to link to other people who were similarly confused if that helps show that this is not as clear as you may think.

[mao-sz]

Technically, you can write tests with SuperTest alone since it provides matcher methods to chain onto request, but you can also use it in conjunction with a general test runner like Jest, whether for familiarity or for more complex tests/assertions.

For the lesson in question, I think it makes more sense for the lesson content to specify the use of Jest and to not even mention other test runners. If learners for whatever reason wish to use a different test runner e.g. Vitest, Node's built-in test runner, Mocha+Chai or even not at all, that's their own decision and they can go through docs as necessary. We don't need to enforce the use of a particular test runner, only make it explicit that the lesson examples will use Jest+SuperTest (because right now the code examples are broken - SuperTest does not provide a test global, so running it will throw an error.

The following two paragraphs:

To facilitate actually testing these routes we’re going to use a library called SuperTest, so go ahead and npm install supertest --save-dev and while it’s installing take a few minutes to look through the readme on their git repo (linked above).

In the examples below we’re going to use SuperTest inside of a Jest style describe/test block, but the syntax and use of these are common among most testing libraries, so the concepts should be easily replicated in Mocha with Chai or Jasmine or Tape or whatever testing library you prefer.

IMO can be tweaked to something like:

To facilitate actually testing these routes we’re going to use a library called SuperTest, and for familiarity of test syntax, we'll use it in conjunction with Jest in this lesson's examples. Go ahead and npm install jest supertest --save-dev and while it’s installing, take a few minutes to look through the readme on their git repo (linked above).

Alternatively, the lesson can just rewrite its few code examples without Jest at all. I'm fine with either approach, with a subtle preference towards just rephrasing the paras above.

---

For now, this should suffice. Currently, the Node course uses CJS only. In a future revamp milestone, we'll be discussing exactly how to approach ESM within Node course (several options have been thrown around in previous discussion but have not been within the scope of WIP milestones yet). When that happens, it's possible this lesson needs revisiting due to Jest's lack of stable compatibility with ESM. I think that's an unnecessary scope to tackle right now, but just providing some context.

@ManonLef do you have any differing/additional thoughts on the above, or any preference for action?

[ManonLef]

I'm fine with your proposal @mao-sz

[mao-sz]

Acceptance criteria

• Rephrase paragraphs as per Testing Routes and Controllers: explicitly state that jest is required to test sample code #30420 (comment)

Please comment below if you'd like to be assigned to work on this issue. Please do not open a PR unless you have been assigned by a maintainer.

[ZackHoang]

I'll take this one on!