Transcripted Summary
Cypress tests run inside a browser, but there is a way to escape from the browser and instead jump into node environment. This enables us to do some tasks that are only available in a node. For example, access our file system, read a pdf or run a script to reset our database.
In this lesson, we're going to be resetting the database. Now, since our database is basically a database json file that contains all of our data, what we are going to be doing is rewriting this file. Now, of course, in real time, the database can get much more complicated, but the thing I want to show you is the fact that you can escape browser, run a node task, wait for it to finish, and then continue on with your test.
I have prepared a script called seed database.js. This script will find its way to the database json file and then write into it using the file system write file sync function. This will take our db path that takes us to the path of the database and then rewrite it with data that we provide inside this seed database function. This function is exported so we can later import that into the file that we want. And then finally, the data that we pass on through the function is going to get returned.
So, in order to run this function, I'm going to go to my test file and add a new command cy task. Now, this command is special because by default it doesn't do anything. It's a dynamic command and we can program it to do whatever we want. This will be our bridge between browser and the node environment. I'm going to put an argument and call it seed database. Now, if I save my test now, I'm going to get an error. Cypress is going to complain that there is no task seed database because we haven't created one. To do that, we need to jump into cypress.config.ts file and add one into setup node events function.
This is where all of our node events or node functions are going to be present. What we want to do now is to define a seed database task. So, let's go ahead and do that by using the on function inside setup node events. You can see this is one of the parameters of this setup node events function. This on function is here to define what should happen on various events during our test. So, one of those events is task. So, whenever a task happens something should be called. That something is defined in the second parameter which will be an object containing all of the names of our tasks.
So, here is the place where we will define all of the things that cytask will do for us. Now, since we have created a task called seed database, we need to define that in our cypress.config. So, let's call it seed database and here we'll define what the seed database should be doing. We can start off simple just by creating a function that's going to return something and let's just say hello world. When I now save my cypress.config.ts file my test is going to be passing because now my seed database actually has a function behind it.
Now, this function doesn't do much. It doesn't seed our database. It just returns hello world and we can see that when we click on the timeline of the seed database, open our console and see what this task has returned. As you can see, we'll see the hello world text in here. Now, of course, that's not what we want. We want to seed our database. So, what we can do now is instead of this function we can call our seed database function. So, to do that I'm going to import this and say import from the file seed database.js and we want to import the seed database function which is the export of this file. So, we are going to insert this function over here into our cypress.config file.
Now, to do that I'm just going to replace it with the seed database and there is a simple trick in javascript where if we have a object like we have here that has the same attribute and the value we can just skip that altogether and javascript will know that when we are referencing the seed database we're pointing to a variable that we have imported here. So, let's now save the test and as you can see it is now failing but we actually have a different error.
Before cypress was complaining that we haven't defined the seed database function but now the error says that we forgot to add the data argument. If you remember in our seed database script we have a parameter in here and we need to pass it. So, back in our test I'm going to add another parameter and the argument I'm going to pass is going to be an object. The reason why this needs to be an object is that I want to follow the same pattern as we have in our database json. We'll see there's an object which has four different parameters boards, cards, lists and users.
Each one of these is an array of objects where every object in the array equals to an item. So, this is a board with the name things to buy and inside cards we have one card inside lists we have one list. So, let's instead of having this kind of database make it completely empty. So, I'll add an attribute boards which will be an empty array then cards again empty lists and then finally users. This is how our database actually looks when it's completely empty. Let's now save my test and as you can see it's now passing.
Inside my application I'm seeing the empty state inviting me to create my first board. If we go take a look into our database we'll see it's completely wiped out. Of course we can define our own data in here and let's say we have a name of hello world id of one start attribute let's set up to true user will be zero and then created date will be 2023 11 13. So, let's save this now and now we can see that our task has seeded the database with our own data. We'll see the hello world which is start and if I click on it I'll see it has id of one.
In general, if you want to use this task and pass an argument to it, it needs to be an object or a single parameter. There's no way of adding multiple parameters so the way we need to construct our function needs to be done in a way that it only accepts a single parameter. Also, it always needs to return data and this is a very simple function that rewrites a json file but if you use a more complicated database inside the script you could connect to the database, wipe out data, seed your own, maybe authenticate, basically do anything that the node.js environment allows you to do.
There are simply no limits to this.
Resources
- .task() command documentation
- Writing a configuration plugin
- My blog on writing configuration plugin (v9)
- Documentation on configuration
- Cypress.config() object
- Cypress.env() object
- Setting up env variables
