DEV Community: Xavier

Connecting Cypress to a PostgreSQL database

Xavier — Tue, 11 Oct 2022 19:42:39 +0000

One of the frequently asked questions in the Cypress Discord channel is; how to set up a Cypress project and connect to a Database. This week I saw the questions pop up for Postgres, Oracle, and Microsoft SQL. Because of this, I thought to create a small series where I describe the various Databases and how to use Cypress to connect to them.
For my first blog, I will start with the easiest one PostgreSQL.

If you want to skip the explanation and see the results, then go directly to my GitHub project: https://github.com/Xvier/cypress-postgres-demo

Prerequisites to get started:

Cypress project
Basic knowledge of cy.task
Postgres Database
PG nodejs library

Let's first set up our Database. For this example, I will be using Docker. But feel free to install Postgres or use a cloud provider if that fits your needs.



FROM postgres
ENV POSTGRES_USER cypress_admin
ENV POSTGRES_PASSWORD cypressrules
ENV POSTGRES_DB cypress

To start the Database we will have to create a container and run it with the following commands:



docker build -t mydatabase .  
docker run -p 5432:5432 mydatabase:latest

If everything running, you will now have a Database online and the following message in your terminal: database system is ready to accept connections.

Let us create a new Cypress project, install the Postgres client, and open Cypress.



npm init -y 
npm install -D cypress pg
npx cypress open --e2e --browser=chrome

Let us create a new spec file in the e2e folder called postgres.cy.js



describe('We will make a connection with Postgres, () => {
  it('First connection', () => {

  })
})

So how do we connect to the Database? For this, we need to utilize a cypress task. With cy.task() we can execute node code.
Example of node libraries:

FS to write files to the operating system
PG to call Databases
bcrypt to hash passwords

So how do we set up a task?
In the cypress.config.js file, we will add the following code.



const { defineConfig } = require("cypress");

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      on("task", {
        connectDB(){
          return "Inside our task"
        }
      })
    },
  },
});

We created a task called connectDB and this will return a string Inside our task.

In our Cypress test, we will now add the following code to our test and view the output in Cypress.



cy.task("connectDB").then(cy.log)

The cy.log yields the string Inside our task.

Now that we know this works we can alter our task code to connect to the Database and get the current Database Date.

Let us change our task to connect to the Database. The following code will make a connection to our local host with the credentials we set in our DockerFile.

To find out how to connect to a Postgres Database you can also check the documentation: https://node-postgres.com/



const { defineConfig } = require("cypress");
const { Client } = require('pg')
module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      on("task", {
        async connectDB(){
          const client = new Client({
            user: "cypress_admin",
            password: "cypressrules",
            host: "localhost",
            database: "cypress",
            ssl: false,
            port: 5432
          })
          await client.connect()
          const res = await client.query('SELECT NOW()')
          await client.end()
          return res.rows;
        }
      })
    },
  },
});

For the time being, we hard coded the query to see if we will get a valid response back.
Let us rerun our test and view the results.

We now see a valid date being send back from the Database.

Now our last step will be to remove the hard coded query value.
To remove the hard coded value we will add a query parameter to our function. With this, we can set the query from our test. Let us add the value query to our method and the await.client.query() statement.

Our final edit looks like this:



       async connectDB(query){
          const client = new Client({
            user: "cypress_admin",
            password: "cypressrules",
            host: "localhost",
            database: "cypress",
            ssl: false,
            port: 5432
          })
          await client.connect()
          const res = await client.query(query)
          await client.end()
          return res.rows;
        }

And in our test, we can pass a query when calling our task



cy.task("connectDB","SELECT NOW()").then(cy.log)

And this will give us the same result as when we did it hard coded.

Now that you have a valid connection you can add, remove and check data in your Database.

Thank you all for reading please check out my repository for a full working sample: https://github.com/Xvier/cypress-postgres-demo

For questions please reach out to me here or in the Cypress Discord Channel: https://discord.gg/cypress

Documenting Cypress custom commands

Xavier — Mon, 06 Dec 2021 19:11:12 +0000

On November 23rd, 2021 I held my talk about documenting Cypress custom commands in the Cypress.io Dutch meetup group. Because of that I thought let me also write a blog about it so that people can get started with this ASAP and not when you have 100 commands.

For the people who want to follow step by step you can check out the manual way, there is also an easy way with using a VSCode plugin and for people interested in my story I also shared the youtube recording of the meetup.

Manual way

The best way to learn something is to do it manually so let's create step by step each file needed so that in the end we have docs and IntelliSense for our custom commands.

One of Cypress's biggest features is having autocompletion(IntelliSense) and seeing what every Cypress command does with an extensive description without going outside your code editor. But this feature comes not out of the box when creating your custom commands. So how can we utilize the same feature Cypress is using, this can be achieved by creating our Type Definition file and extending the default Cypress types.

Setup

So to start we need a jsconfig.json in the root folder or a tsconfig.json file in our cypress folder. I will use a tsconfig file for this example but I will give you also a jsconfig example file.

`./jsconfig.json`

{
  "include": ["./node_modules/cypress", "cypress/**/*.js","./types/*.d.ts"]
}

`./cypress/tsconfig.json`

{
  "compilerOptions": {
    "allowJs": true,
    "baseUrl": "../node_modules",
    "types": [
      "cypress"
    ],
    "noEmit": true
  },
  "include": [
    "**/*.*"
  ]
}

This will enable basic intellisense in all our files and the option to extend it with our own commands.
Now lets create a custom command called devSpecialCommand and place it in our commands file.

`./cypress/support/commands.js`

Cypress.Commands.add('devSpecialCommand', (text, number) => { 
    cy.log(`This is our special command lets printout the text ${text} and the number ${number}`)
})

To add Intellisense and documentation we need to create a Type definition file. To keep it simple I will create a types folder inside our cypress project and call the file types.d.ts. Now lets add our the following code to this file so that we can start documenting our command.

`./cypress/types/types.d.ts`

declare namespace Cypress {
  interface Chainable<Subject> {
    devSpecialCommand(text: String, number: Number): Chainable<any>;
  }
}

We extended the Cypress namespace and added our custom command to the list of options. When you press cy.d in one of your testfiles it will give you the option cy.devSpecialCommand

This still looks plain since we do have IntelliSense but we still have no idea what this plugin does. To add a better description we are going to utilize the jsdoc in our Types file to describe what the feature is for.

Lets go back to our types file and add some description.

    /**
     * @description This is a demo command for the dev.to blog
     * @param {string} text - Enter a random text
     * @param {number} number - Enter a number
     */
    devSpecialCommand(text: String, number: Number): Chainable<any>;

When we hover over our command implementation we now get a detailed view of what our command does and what the input fields are.

Now you have a way to document your command and make it readable for all users what the command is supposed to do. If you want to know more about documentation I suggest reading the jsdoc page of all possible annotations.

If after reading you have difficulties getting it to work you can also clone my demo repository cypress custom commands

Easy way - VSCode plugin

When using VSCode there is an easy way of creating documentation or having IntelliSense to your Cypress project. So no more doing stuff by hand let us use a plugin to fix all the manual stuff.

First of you need the plugin Cypress Helper

This plugin will do all the manual work for you and gives you a few features extra like:

Creates the Type Definition file with the custom command name.
If no jsconfig/tsconfig file is present then it creates a tsconfig.json file.
Gives you the option to go to the custom command with a shortcut.
Find unused custom commands.

With the plugin installed right-click in your custom commands file and select Cypress: Generate Custom Commands Types. This will generate a customCommand.d.ts file with your custom commands.

A tip look in your notification tab of VSCode sometimes you won't get a popup to create a tsconfig file but if you click on the notification icon you will see the option. Now you can add documentation in the same way as the manual way.
Thank you all for reading and if you want to watch the meetup recording you can do so below.

DEV Community: Xavier

Connecting Cypress to a PostgreSQL database

Documenting Cypress custom commands

Manual way

Setup

./jsconfig.json

./cypress/tsconfig.json

./cypress/support/commands.js

./cypress/types/types.d.ts

Easy way - VSCode plugin

Meetup Video - Skip to 23:05 for the demo

`./jsconfig.json`

`./cypress/tsconfig.json`

`./cypress/support/commands.js`

`./cypress/types/types.d.ts`