DEV Community: Thomas Peklak

How to test a Hasura Api with Jest

Thomas Peklak — Fri, 27 Aug 2021 06:51:18 +0000

Hasura provides an easy way to build an API and testing it is as easy as testing any other API. We will focus on the GraphQL API but everything presented here can be applied to the REST API as well.

Use Case

We will model a todo list for different users. Each user should only see her own todo items and none of a different user.

Tools

We will use

Docker: to setup Hasura and PostgreSQL
Jest: as our test runner
graphql-codegen: to generate an SDK including Typescript support to have good autocompletion in the editor
JWT: to set the authenticated user

... to test that the business logic in Hasura works as intended. Business logic can live in Hasura itself (e.g. permissions) or within the database (e.g. views, constraints, et al.). Note that it does not make sense to test that Hasura does its job correctly as it is by itself well tested. If you just create a resource without any logic you probably do not want to test it.

If you want to follow along you can clone the sample repository at trigo/hasura-api-testing.

Hasura and PostgreSQL Setup with Docker Compose

We use a slightly modified version of Hasura's docker compose file.

Changes include:

HASURA_GRAPHQL_JWT_SECRET for user authentication
cli-migrations image so that migrations are automatically applied
graphql-engine/volumes to be able to store migrations and metadata in the repository
exposed port for PostgreSQL to be able to connect directly to PostgreSQL

// docker-compose.yml
version: "3.6"
services:
  postgres:
    image: postgres:12
    restart: always
    ports:
      - "5432:5432"
    volumes:
      - db_data:/var/lib/postgresql/data
    environment:
      POSTGRES_PASSWORD: password
  graphql-engine:
    image: hasura/graphql-engine:v2.0.3.cli-migrations-v3
    ports:
      - "8080:8080"
    depends_on:
      - "postgres"
    restart: always
    volumes:
      - ${PWD}/migrations:/hasura-migrations
      - ${PWD}/metadata:/hasura-metadata
    environment:
      HASURA_GRAPHQL_METADATA_DATABASE_URL: postgres://postgres:password@postgres:5432/postgres
      PG_DATABASE_URL: postgres://postgres:password@postgres:5432/postgres
      HASURA_GRAPHQL_ENABLE_CONSOLE: "true"
      HASURA_GRAPHQL_DEV_MODE: "true"
      HASURA_GRAPHQL_ENABLED_LOG_TYPES: startup, http-log, webhook-log, websocket-log, query-log
      HASURA_GRAPHQL_ADMIN_SECRET: admin-secret
      HASURA_GRAPHQL_JWT_SECRET: '{"type":"HS256", "key": "3EK6FD+o0+c7tzBNVfjpMkNDi2yARAAKzQlk8O2IKoxQu4nF7EdAh8s3TwpHwrdWT6R", "claims_map": { "x-hasura-allowed-roles": { "path": "$$.roles" }, "x-hasura-default-role": { "path": "$$.roles[0]" }, "x-hasura-client-id": { "path": "$$.clientId", "default": "" }, "x-hasura-user-id": { "path": "$$.userId", "default": "" }, "x-hasura-username": { "path": "$$.username", "default": "" } }}'
volumes:
  db_data:

Start Hasura and PostgreSQL with docker-compose up -d and wait until Hasura is up and running. You can either check via curl localhost:8080/healthz or hasura migrate status --admin-secret admin-secret to see whether all migrations have been applied.

Setup Database and Permissions

When you spin up the compose file within the provided repository you can skip the next steps because migrations and metadata are included and applied automatically when Hasura starts.

Next we create a todo table with properties id, description, is_done, and user:

CREATE TABLE "public"."todo" (
  "id" serial NOT NULL,
  "description" text NOT NULL,
  "is_done" boolean NOT NULL DEFAULT false,
  "user" text NOT NULL, PRIMARY KEY ("id")
);

Permissions

Insert permissions:

When inserting new todos, we do not allow the user to set the user property by herself, instead we use the user-id session variable for the user and only allow the properties description and is_done to be set. id is an autoincrement field and should not be touched by the user either.

Select permissions:

When a user retrieves her todos, we set the custom check user equals x-hasura-user-id to ensure that a user only gets her own todos.

We have now completed our PostgreSQL and Hasura setup and are ready to look into the test setup.

Tests

Code Generation

We leverage @graphql-codegen to generate an SDK for the GraphQL API. It will take all .graphql files under tests, connect to the Hasura GraphQL API and output the SDK in tests/client/graphql.request.ts. This takes over most of the communication between our tests and the GraphQL API and gives us typing information to help us in the editor and in our tests.

You can find detailed information at GraphQL Code Generator on the possibilities to generate code from your GraphQL schema.

First we need a .graphql file that describes how to insert and select todos. It has a query GetTodos that retrieves
all todos and a mutation AddTodo which inserts a new todo item.

// tests/graphql/todo.graphql
query GetTodos {
  todo {
    id
    description
    is_done
  }
}

mutation AddTodo($description: String = "", $is_done: Boolean = false) {
  insert_todo(objects: { description: $description, is_done: $is_done }) {
    returning {
      id
    }
  }
}

graphql-codegen/cli needs a configuration file so it knows where our GraphQL API lives, where to look for source files and where to put the generated SDK. You can also specify plugins which modify the output of SDK. More information can be found in the graphql-codegen plugin index.

We will use

typescript: Generate types for TypeScript - those are usually relevant for both client side and server side code
typescript-operations: Generate client specific TypeScript types (query, mutation, subscription, fragment)
typescript-graphql-request: Generates fully-typed ready-to-use SDK for graphql-request

// codegen.js
module.exports = {
    schema: [
        {
            'http://localhost:8080/v1/graphql': {
                headers: {
                    'x-hasura-admin-secret': 'admin-secret',
                },
            },
        },
    ],
    documents: ['./tests/**/*.graphql'],
    overwrite: true,
    generates: {
        './tests/utils/graphql.request.ts': {
            plugins: [
                'typescript',
                'typescript-operations',
                'typescript-graphql-request',
            ],
        },
    },
};

Now install all necessary npm modules

npm install -D @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-graphql-request @graphql-codegen/typescript-operations

and generate the SDK with npx graphql-codegen --config codegen.js. This should generate an SDK under tests/utils/graphql.request.ts.

Authenticated Requests

The SDK itself does not have an easy way to create authenticated requests with JWT, you need to generate and specify the headers for each request. But we can simply wrap it for our purposes so that authentication headers are automatically sent with each request. The configuration will be sourced from the .env file which should include Hasura and PostgreSQL configuration variables, see .env example

// tests/utils/client.ts

import {GraphQLClient} from 'graphql-request';
import {getSdk} from './graphql.request';
import jwt from 'jsonwebtoken';
import dotenv from 'dotenv';

// source environment variables
dotenv.config();

We have set up the imports and read in the configuration variables. We can now extract the key from the Hasura configuration parameter (see docker-compose.yml above).

let secret = '';
try {
    secret = JSON.parse(process.env.HASURA_GRAPHQL_JWT_SECRET!).key;
} catch (e) {
    console.error(
        'HASURA_GRAPHQL_JWT_SECRET must be parsable json and have property key'
    );
    process.exit(1);
}

The client takes options for either a user or an admin:

User:
- allowedRoles: all roles that a user can have, this will be sent within the JWT
- defaultRole: the role that is currently active, is sent in the x-hasura-role header, but must also be present in the JWT
- userId: the user id
- username: the username
Admin:
- admin: boolean used to make requests with the admin-secret. No other option needs to be present

type UserOptions = {
    allowedRoles?: string[];
    defaultRole: string;
    userId: string;
    username: string;
};

type AdminOptions = {
    admin: boolean;
};

// define the configuration options for the client
type Options = UserOptions | AdminOptions;

If we have a user we map the default role to the x-hasura-role header which corresponds to the role in the Hasura Console permissions tab.

const mapOptionsToHeaders = (options: Options) => ({
    'x-hasura-role': options.defaultRole || '',
});

All other user options are packed into the JWT which will be read by Hasura and provided as variables for permissions.

const generateJwt = (options: Options): string =>
    jwt.sign(
        JSON.stringify({
            roles: options.allowedRoles || [],
            userId: options.userId,
            username: options.username,
        }),
        secret
    );

We can now create the main entry point which takes the options and returns an SDK with a user specific GraphQL client embedded.

export default (options: Options): ReturnType<typeof getSdk> => {
  if (!process.env.GRAPHQL_ENDPOINT) {
    throw new Error("GRAPHQL_ENDPOINT is not defined");
  }
  if (!process.env.HASURA_GRAPHQL_ADMIN_SECRET) {
    throw new Error("HASURA_GRAPHQL_ADMIN_SECRET is not defined");
  }

  // if we do not provide allowedRoles for the client we assume that the defaultRole is an allowed role
  if ('defaultRole' in options && !options.allowedRoles) {
    options.allowedRoles = [options.defaultRole];
  }

We configure a GraphQL client with either an admin user (with an admin secret) or a normal user (with JWT) and pass it to the SDK factory function. This will ensure that all request have the correct headers.

  const client = new GraphQLClient(process.env.GRAPHQL_ENDPOINT, {
    headers: 'admin' in options
      ? { "x-hasura-admin-secret": process.env.HASURA_GRAPHQL_ADMIN_SECRET }
      : {
          Authorization: `Bearer ${generateJwt(options)}`,
          ...mapOptionsToHeaders(options),
        },
  });

  return getSdk(client);
};

Testing Todo Permissions

Recap: We want to ensure that users see only their respective to todos.

Steps:

clear the database before each test
create 2 todos for user Franz
create 1 todo for user Herbert
get todos for user Franz
get todos for user Herbert
test that each user sees only his todos

Import dependencies

import clearDb, {closeConnection} from './utils/clear-db';
import client from './utils/client';

Setup the test and hooks

describe("Todo", () => {
  // reset the database before each run
  beforeEach(clearDb);

  // close PG connection after all tests
  afterAll(closeConnection);

Create an SDK client for each user. We provide the defaultRole (user), a username and a userId all client requests are scoped to the passed in options.

  describe("user: Franz + Herbert", () => {
    it("should only see his todos", async () => {
      const franzClient = client({defaultRole:'user', username:'franz', userId:'1'});
      const herbertClient = client({defaultRole:'user', username:'herbert', userId:'2'});

Insert two todos into the database for user Franz

const franzTodo1 = await franzClient.AddTodo({
    description: "Franz's first todo item",
    is_done: false,
});
const franzTodo2 = await franzClient.AddTodo({
    description: "Franz's second todo item",
    is_done: false,
});

Insert one todo for user Herbert

const herbertTodo1 = await herbertClient.AddTodo({
    description: "Herbert's first todo item",
    is_done: false,
});

Now we have three todos in the database two for Franz and one for Herbert. We retrieve the todos for each user and assert that the user only sees his own todo items.

      // get Franz's todos
      const franzsTodos = await franzClient.GetTodos();

      // Franz should only see his todos
      expect(franzsTodos.todo.map(todo => todo.id).sort())
        .toEqual([
          franzTodo1.insert_todo?.returning[0].id,
          franzTodo2.insert_todo?.returning[0].id]);

      // get Herbert's todos
      const herbertsTodos = await herbertClient.GetTodos();

      // Herbert should only see his todos
      expect(herbertsTodos.todo.map(todo => todo.id).sort())
        .toEqual([herbertTodo1.insert_todo?.returning[0].id]);
    });
  });
});

Conclusion

It is really easy to setup a Hasura API but with this ease we often forget that business logic should be well tested. As soon as the test setup is done it is rather easy to write tests against the API. TypeScript and the tests help to see any breaking API changes that would let your application fail in production.

Notes

Due to the current setup it is not possible to run tests in parallel. The API tests provide no means to isolate a test in a transaction. Keep this in mind as it will increase the time of your test runs.

This is all just a starting point.

Develop Electron in Docker

Thomas Peklak — Wed, 25 Aug 2021 14:30:10 +0000

Why

There are several reasons to develop in Docker and not on your host machine. First, when it comes to backend services, you can guarantee that your development runtime is the same as in production, which can eliminate some scenarios where inconsistencies can lead to problems in production.

Of course, this doesn’t really apply to Electron because their apps are bundled up and shipped to your users — here you don’t have any control over the environment. Even so, you can have build dependencies where you want to have either an easier setup for the whole development team or you want to guarantee that every developer has the same system dependencies as your build servers installed.

My case was different: my colleague had to introduce a new dependency with a native module. It worked well on his machine, but created a segfault on mine. I’m not familiar with debugging segfaults and getting my development setup up and running again was urgent. Before I turned to Docker I tried different versions of Electron and the library but always ended up with the same result: it worked on other machines but not on mine. The library even worked well using the corresponding NodeJS version there only seemed to be a problem with Electron.

As I thought that this was just a temporary issue and would be fixed in future versions of the library or Electron, I was happy to have a temporary solution.

How

Based on this directory structure we can build a Docker image from a Dockerfile which installs all node modules, performs an electron rebuild, and does some other black magic.

Directory Structure

package.json
package-lock.json
Dockerfile
src
- main.js
- index.html

It’s important that your files are not located in the root folder because we want to mount the source directory into the container, so we can continuously work without rebuilding the image. We only need to rebuild the image if there is a change in the npm dependencies.

# use the version that corresponds to your electron version
FROM node:14.16

# install electron dependencies or more if your library has other dependencies
RUN apt-get update && apt-get install \
    git libx11-xcb1 libxcb-dri3-0 libxtst6 libnss3 libatk-bridge2.0-0 libgtk-3-0 libxss1 libasound2 \
    -yq --no-install-suggests --no-install-recommends \
    && apt-get clean && rm -rf /var/lib/apt/lists/*

# copy the source into /app
WORKDIR /app
COPY . .
RUN chown -R node /app

# install node modules and perform an electron rebuild
USER node
RUN npm install
RUN npx electron-rebuild

# Electron needs root for sand boxing
# see https://github.com/electron/electron/issues/17972
USER root
RUN chown root /app/node_modules/electron/dist/chrome-sandbox
RUN chmod 4755 /app/node_modules/electron/dist/chrome-sandbox

# Electron doesn't like to run as root
USER node
CMD bash

Now, we can build the Docker image and start a container. If you have other files and folders in your root directory, you need to mount each single one separately. You can’t mount the root directory as this will also overwrite the node modules.

docker build -t electron-wrapper .
docker run -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=unix$DISPLAY -v`pwd`/src:/app/src --rm -it electron-wrapper bash

This should fire up a bash prompt from which you can start your development workflow, e.g. npm start.

Example `package.json`

{
    "name": "electron-in-docker",
    "version": "1.0.0",
    "description": "",
    "main": "src/main.js",
    "scripts": {
        "start": "electron . --no-sandbox"
    },
    "author": "",
    "license": "ISC",
    "devDependencies": {
        "electron": "^13.1.7",
        "electron-rebuild": "^2.3.5",
        "libxmljs": "^0.19.7"
    }
}

Conclusion

This guide works in Linux and likely in WSL2. For macOS, you can take a look at Jake Donham's blog post in the links below, which helped me a lot to get started. I always find it good to have some backup in my developer's toolbox if things break in unpredictable ways. Running programs in Docker is one of my all-time favorites.

Example repository

If you want to try it out yourself, you can take a look at the electron in docker repository.

DEV Community: Thomas Peklak

How to test a Hasura Api with Jest

Use Case

Tools

Hasura and PostgreSQL Setup with Docker Compose

Setup Database and Permissions

Permissions

Tests

Code Generation

Authenticated Requests

Testing Todo Permissions

Conclusion

Notes

Develop Electron in Docker

Why

How

Example package.json

Conclusion

Further reading

Example repository

Example `package.json`