[Track 5/9] The tests 🤓

[taki-tiler-server[bot]]

Step 1/6 - First test setup

Estimated time: 1 hour

Now you're going to work on another super-important concept on the process of building your own server. Have you ever stopped to think about how you would test if your code works? 🤔 If you thought about performing the query/mutation on one of those applications (browser, graphiql, graphql playground) and checking if it works as expected, that's one way of doing it. But we have a more solid proposal: writing more code for tests! The principle is simple: you give an input and check if the response is the expected. Why is it better? Well, some advantages:

1. The time gain: you write your test once, and then you can run it whenever you want.
2. While you develop other features, you can keep running the tests for all the previous implemented queries/mutation to make sure they are still working.
3. Test codes can serve as a kind of documentation as well. People who read them are able to know all the particular scenarios of a query/mutation.

If you search on the Internet, you'll find out there are many ways to test a code. Depending on the project, people decide to use one, or several of them. Here, we're going to write E2E tests (end-to-end). For each query/mutation of your server, you're going to setup the database for them, provide some input scenarios, and then check if the response is given as expected. Take some minutes to read about them on the Internet.

Setting up tests on your server is not an easy task. There are a couple of things to learn and prepare first. We're going to create a step-by-step to help.

As you can imagine, giving the previous steps, there are more cool libraries to help us on this process. We're going to present them one at a time.

The first one is the main library to write the tests codes: mocha. Take a look at their docs. It's important to know that mocha provides some methods that can be executed like a timeline. This is very useful to handle tasks in specific orders.

Your task is very simple in this first step:

• Install the library. You can use the devDependencies to install it. Would you be able to say why? 🤔
• Create a test folder on the root of your project with an index.ts inside it.
• Create a script on your package.json to run your tests with npm run test
• Write a simple test with describe/it that just prints something. If it's running properly, go to next step.

[marco-prado]

next

[taki-tiler-server[bot]]

Step 2/6 - Libraries everywhere: supertest

Estimated time: 2 hours

Another of those cool libraries is supertest. This library makes our work of performing requests to the server easier. Take a look at their docs.

Now, let's increment our step-by-step for the test execution:

1. Start the server
2. Run a single test

In order to acomplish this new first step, your task is to:

1. Install the library
2. Change your code to start the server before(() => {}) beginning the test... (🤣)
3. Use the request function of supertest to communicate with the server you just started. You can use the localhost:port for this.
4. Try to perform your previously implemented hello query, from the apllo-server setup. For now, just check if it's working with console.log

NOTE: you can open a pull request after this step, so we can check if your setup is going ok for now.

[marco-prado]

next

[taki-tiler-server[bot]]

Step 3/6 - The last library (for now): chai

Estimated time: 30 minutes

The last library for tests is chai. Chai is a very complete library that handles assertion, i.e., checking if the result has the values that were expected to have. As usual, take a look at theis docs, install it on your project and try to use the expect function to compare the return of your Hello query with the expected value.

Try to use these functions as if you were writing a sentence, to improve readability. For example:

expect(queryResponseField).to.be.eq('Hello, Taqtiler!');

[marco-prado]

next

[taki-tiler-server[bot]]

Step 4/6 - Database and environments

Estimated time: 1 hour

Now we're going to include the database on our tests. After all, we should test if our queries will be returning what is on the database correctly, and if our mutations are changing the database accordingly.

Do you remember we talked about setting up 2 containers because we were going to use 2 databases? Yeah, the north remembers 🐺! As a preparation for this step, you're going to setup 2 environments: the one you're already using to develop with npm start and one additional to run the tests. Do some research about the importance of having separate environments on our development workflow. We will talk about it on our meetings too.

One way of handling separate environments is to use environment variables. They are variables that can be set for each environment, so when we start our server on that environment, we use the specific values for it. We could have as environment variables, for example, our database host, user, url, etc...

Your task now is to set some environment variables to connect with the right database for each environment: localhost and test. Create a .env and a test.env file to store the values of these variables. This package can help you on reading the right file depending on the environment you're running.

Now, our step-by-step for the tests is incremented again:

1. Connect to database (the test one)
2. Start the server
3. Run the "hello" query test

NOTE: remember that previous note about async tasks and Promises? Here's another example that we should use it properly, because before start running the tests (not that joke again), you should verify:

• if the connection with the database is finished successfully
• if server is successfully running and listening to port X.

After it all, you can run the tests.

[marco-prado]

next

[taki-tiler-server[bot]]

Step 5/6 - The "createUser" Mutation test

Estimated time: 3 hours

Now it's time to (finally) write the tests for your recently implemented createUser mutation. But first, some theory: unlike our simple Hello query, this mutation is integrated with database. How should be these tests? Well, some general good practices every test you're going to perform: replace your current 3. run a single test step with:

• Setup the database: to check if some feature is working, most of the time we need to have a certain state on the database before running the test. In this case, we should only need the user table properly setup, something we should already have by now.
• Create an input: you should create one example of input to run your query/mutation. On this example, it should be those user input fields.
• Run the test: well.... Run the test 🏃.
• Check the response: Given the input and the state of database previously set up, you should check if the response is returned as expected. On a successful user creation, an id should be generated and the user info should be returned. Check all fields to increase the test completeness.
• Check the database after the test: we should check not only if the return is ok, but also if the user was created on database properly, and all fields are in accordance with the input. Also, don't forget to check the password, it should be hashed.
• Clear the database: we want our tests to be independent, so we can make sure every piece of our lego works and can be properly united on a good system. So, it's important to reset the state of the database after every test. This way, one test has no influence on other tests. You can read more about the importance of independent tests on the internet. We should talk about this too.

NOTE: don't forget to open a PR with your test.

[marco-prado]

next

[taki-tiler-server[bot]]

Step 6/6 - Error handling

Estimated time: 2 hours

Now it's time to make our createUser mutation as complete as possible with the promised error handling. For that, we're going to predict and treat some possible errors. Let's take those cases we already predicted before:

1. The client sends an e-mail that already exists on our database
2. The client sends a password that doesn't follow the rules of security

As already said, there are more possibilities, but these 2 are ok for the onboard. What do you think we should do on these scenarios besides throwing a generic error?

Well, there are multiple solutions to that, but we have a suggestion. Let's return the following structure on the errors field:

{
  code: number;             // Conveniently equal to the HTTP protocol status code
  message: string;          // Message to describe the error
  additionalInfo?: string;  // Additional info, generally good for the client developer to know more of what happened
  // ... GraphQL default fields
}

You should be able to research and find how you can treat errors when you find one on your code, but it's basically throwing an error and treating it on a proper function that the apollo-server library receives on the server setup. Check their docs 😝

Your task now is:

1. Implement the error function to change the default error that is returned. Note that the error thrown at the code will not directly be the parameter of the function. Instead, apollo-server puts it on o field called originalError. You can see it in their docs or test with some logs.
2. Create a class that extends Error and receives the code, the message, and optionally, the additionalInfo.
3. When you identify the errors on the scenarios described above, throw an error of this class you created with the proper parameters.
4. Now, create additional test cases for your createUser with those 2 (or more) scenarios, checking if the returned error is as expected.

[marco-prado]

next

[taki-tiler-server[bot]]

Click here for your next track