00:08
It's a great testing framework for any Node.js project using ESM as well as TypeScript. And it does come with everything that you're going to need for testing backend frameworks
00:17
like assertions, including open API assertions, an API client for testing your endpoints, a browser client for doing full browser tests with Playwright, file system helpers, snapshots,
00:27
and all of that fun stuff. Throughout this series, we will take a look at the assertion plugin, the open API assertions briefly, the API client, and briefly the browser client as well.
00:36
You can find the full Japa docs at Japa.dev. If you're looking specifically for the AdonisJS 6 documentation integration with Japa, you
00:44
can go to docs.adonisjs.com and there is a testing section right down here that covers that. As I mentioned, Japa will come pre-configured with most AdonisJS starter kits.
00:54
To ensure that we're focusing on testing, I've gone ahead and prepared a starter repository for this series that has code that we'll be testing within it.
01:01
Nothing has been altered whenever it comes to Japa or its integration within this project. So from that aspect, we can treat this like a brand new project with some pre-written code inside of it.
01:11
Okay, so let's go ahead and get this installed on our system. So let's go and jump into our terminal to do that. And we can use the npm init AdonisJS at latest command to do this using the custom starter
01:21
kit flag. So we'll do hyphen hyphen, and then a space hyphen capital K to pass in a custom starter kit. And then we pass in the repository username.
01:30
So we do attacast there slash testing with Japa starter.
01:35
That just takes the repository identifier there within the repository username. Perfect. Hit enter for that and it will pull it down first asking us where we want to put it.
01:45
So I'm already in the folder that I want this to reside within. So I'm just going to name this testing with Japa, hit enter on that, and it will download that starter kit and install the packages.
01:55
And once that has completed, we can go ahead and CD into testing with Japa and clear our terminal out. Next, let's get that opened up inside of our text editor.
02:04
I'm going to use Visual Studio code for this. So we'll go open code series, testing with Japa, open that up. Perfect.
02:12
And you might get some warnings about not being able to fetch your routes. That's because we have some environment variables to set up here that this repository does require.
02:21
So let's go ahead and do that next. So let's jump into our .emv and what we're going to want to do is add in an SMTP username and an SMTP password.
02:31
And then we'll also want to dig into our browser once again, and we can go into a new tab and go over to mailtrap.io. If you don't already have an account for this, you can go ahead and sign up.
02:41
It's a quick process. If you do, then you just need to go ahead and log in. My account does have two-factor authentication, so I won't take you through that. I'm already logged in here.
02:49
What we want to do is set up an email sandbox here. So we'll go ahead and do start testing. These sandboxes allow you to set up an SMTP endpoint to send emails to, but they won't
02:58
actually send to the actual recipient. Instead, MailTrap will capture them and display them here for us. So we'll head over to add sandbox right over here.
03:06
We can give it a name, Japa testing or something like that, hit save, and that will create our test sandbox.
03:13
We can dig into here where we then see our credentials. So we'll want to click just on the text right there to copy the host, jump back into our
03:21
text editor, and that goes into the SMTP host. We want to do the same with the port. Any one of these four will work. I tend to do 2525, paste that in there.
03:29
Then we need to do it for our username as well as our password, and we should now be all set and ready to go.
03:35
We can confirm everything's working by jumping back into our terminal, node ace list routes.
03:42
And if you get your routes listed out, then everything should be good to go. This also kind of gives you an idea of what's going on within this project thus far as well.
03:50
We have drive set up within this for file uploads. We have a homepage, a jumpstart page, a JSON page.
03:56
We have posts, authentication, password reset, some settings, and almost all of these we're going to cover with tests.
04:05
So let's go ahead and clear that out and we can jump back into our text editor and let's see where Japa resides inside of here. So if we look through the root of our project, you'll notice that we have this tests folder
04:15
right here. If we expand this currently, all we have is a bootstrap.ts. This is where Japa configures its plugins, its runner hooks, and configures its test
04:25
suites as it boots up and shuts down. Now in addition to this bootstrap.ts file, we're also going to have a folder within our tests folder for each of our test suites.
04:35
Test suites provide a way to group tests by their type. The most common test suite are functional or unit tests. Our functional tests will go within a tests functional folder and our unit tests will
04:45
go within a tests unit folder. Unit tests are for testing single functions in isolation from everything else.
04:52
So they're great for testing complex logic inside of like service methods, for example. Additionally, our Adonis server isn't booted for these.
05:00
We can see that right down here inside of our configure suite. The Adonis HTTP server is going to be started for our browser functional or end-to-end or
05:08
E2E here test suites. We can change this at any point in time if we were to like that to be any different.
05:15
Functional tests are for testing from the outside in, like performing actual HTTP endpoint requests.
05:22
We can then use those to verify that the response we get is the exact expected response we would like to see. For these, as we can see right down here, our AdonisJS HTTP server will be booted.
05:32
And that allows us to actually send endpoint requests to our server so that we run through the full controller and middleware logic needed there.
05:39
As I mentioned in the last lesson, we will be discussing browser tests briefly at the end of the series. Browser tests are similar to functional tests, but they go a step further and actually run
05:49
inside of a browser instance from Playwright. So we'll still be able to test actual endpoints with it. So sending out a request to a URL and getting a response back, but we'll then be able to
05:59
use Playwright to make assertions against the actual HTML that was returned back, just like it was a document itself inside of a browser.
06:07
So this configure suite within our bootstrap.ts is where we can hook into the suite's configuration step to do things like booting our HTTP server or anything else that we might need via a
06:17
lifecycle hook like this. But they're actually defined as for where Japa should look within our AdonisRC.ts file.
06:23
If you scroll down a little bit, you'll have this test section with the suites as an array describing where Japa should look for those files on a per suite basis.
06:33
So here you can see we have our unit looking within tests unit and our functional looking within tests functional. We will also add our browser unit here whenever we get to that.
06:42
Great, so let's go ahead and get started with our first test in the next lesson.
