Tutorials


While Cypress has greatly simplified E2E testing for developers, it can still be tricky at times. For example, a best practice while running E2E testing is bypassing the UI when testing pages behind user authentication. 

The Cypress team, in particular, has long advocated for programmatically authenticating users when testing code not related to the authentication flow.

For example, if you are testing your Dashboard code, there is no need to use the UI to authenticate your users: this will only result in slower, heavier and more flaky E2E tests.

In this post, we show you how to sign in programmatically with Supabase Authentication to improve the speed of your Cypress tests and increase their reliability.

## Adding a Cypress command to sign-in programmatically

Cypress allows us to write global commands that we can access using the `cy` variable, which is globally available in all our Cypress tests.

To do so, we will extend Cypress commands with a new command we will name `signIn`, and will be available to us using `cy.signIn()`. Neat, isn't it?

First of all, we want to play nice with Typescript. That means we extend the Typescript's interface in a filename we name `global.d.ts`:

```tsx title="global.d.ts"
namespace Cypress {
    interface Chainable {
      signIn(
        redirectPath?: string,
        credentials?: { email: string; password: string }
      ): void;
    }
  }
}
```

Now, we can extend Cypress with a custom command named `signIn`. To do so, we add a command using the method `Cypress.Commands.add`:

```tsx
Cypress.Commands.add(
  'signIn',
  (
    redirectPath = '/',
    credentials = {
      email: Cypress.env(`EMAIL`) as string,
      password: Cypress.env(`PASSWORD`) as string,
    }
  ) => {
    // body
  }
);
```

The above function takes two parameters:

1. A path where to redirect users after signing in
2. The user credentials, but by providing some default values using environment variables

Let's now write the body of the function:

```tsx
// the function we will define to sign users in
signInProgrammatically(credentials); // <--- implementation is below

// after sign-in, we redirect the users to the provided path
cy.visit(redirectPath);
```

### Signing in using Cypress sessions

If you are using Cypress 12, you will need to use `cy.session`. The `cy.session` command will preserve the session cookie between tests, otherwise, the user will get logged out.

```tsx
Cypress.Commands.add(
  'signIn',
  (
    redirectPath = '/',
    credentials = {
      email: Cypress.env(`EMAIL`) as string,
      password: Cypress.env(`PASSWORD`) as string,
    }
  ) => {
    cy.session([credentials.email, credentials.password],
      () => {
        cy.log(`Signing in with ${credentials.email}`);
        signInProgrammatically(credentials);
      }
    );

    cy.visit(redirectPath);
  }
);
```

## Using the Supabase SDK to authenticate users in Cypress E2E tests

To sign our testing users in without having to interact with the application's UI, we will use the Supabase client SDK.

First, we initialize the Supabase client using the `SUPABASE_URL` and `SUPABASE_ANON_KEY` environment variables:

```tsx
function getClient() {
  const url = Cypress.env(`SUPABASE_URL`);
  const key = Cypress.env(`SUPABASE_ANON_KEY`);

  invariant(url, `Missing SUPABASE_URL env variable`);
  invariant(key, `Missing SUPABASE_ANON_KEY env variable`);

  return createBrowserClient(url, key);
}
```

### Signing users in

Now that we can create an instance of the Supabase SDK, we can use it to sign users in programmatically:

```tsx
function signInProgrammatically(credentials: {
  email: string;
  password: string;
}) {
  const { email, password } = credentials;

  return getClient()
    .auth.signInWithPassword({
      email,
      password,
    })
    .then((response) => {
      if (response.error) {
        return Promise.reject(response.error.message);
      }
    })
    .catch((e) => {
      console.error(e);

      return Promise.reject(e);
    });
}
```

Finally, the `signInProgrammatically` function completes the `cy.signIn()` command defined in the beginning.

## Writing a Test that signs users in programmatically

Whenever you write tests that require users to be signed in, you can write the below:

```tsx
describe(`Create Invite`, () => {
  const email = `invited-member@makerkit.dev`;

  before(() => {
    cy.signIn(`/settings/organization/members`);
  });

  // your tests go here
});
```

As you can see, we can pass any path to the `signIn` function: after signing in, we redirect the users directly to that page, rather than having to use the UI. 

By programmatically signing users in, we will dramatically improve your E2E tests' speed and make them more reliable. Regardless, no need to test the authentication page over and over!

Programmatic Authentication with Supabase and Cypress


Resetting your database state when executing your E2E tests is a common practice to ensure that your tests are isolated from each other. This is important because you don't want to have to write your tests in a specific order or rely on the state from a previous test. 

This is a common cause of flakiness, and it's best to avoid it. In this tutorial, we'll show you how to reset the Supabase database in Cypress E2E tests, so that you can write your tests in any order and not worry about the state of the database.

While this tutorial is written for Cypress, the same principles apply to other E2E testing frameworks.

## When should you reset the database?

There are two ways to reset the database in Supabase:

1. by writing a plugin that resets the database before each spec (or test)
2. by manually resetting the database in your tests where you need it

While the first option is the easiest, it may not always be the best. If you have a lot of tests, resetting the database before each test can slow down your tests significantly. 

Generally speaking, if your tests are well-written, you may not need to reset the database before each test. If you find that your tests are flaky, then you should consider resetting the database before each test.

## Writing an NPM script to reset the database

First, we want to add a new npm script to our `package.json` file

```json
"supabase:db:reset": "supabase db reset"
```

If you want to debug the database reset, you can add the `--debug` flag to the command.

```json
"supabase:db:reset": "supabase db reset --debug"
```

## Writing a Cypress plugin to reset the database before each test

Let's take a look at how we can write a Cypress plugin to reset the database before each test. 

If you are using a newer version of Cypress, we will write plugins using the configuration file `cypress.config.ts`. 

Let's write a function that calls the `npm` script we wrote earlier.

```ts title="cypress.config.ts"
import { execSync } from 'child_process';

function resetDb() {
  console.log(`Resetting database...`);

  try {
    execSync('npm run supabase:db:reset');

    console.log(`DB reset successful`);

    return true;
  } catch (error) {
    console.error(`DB reset failed`, error);
  }

  return false;
}
```

Now, we can use this function in a Cypress plugin. To do so, we will use the `setupNodeEvents` function:

```ts title="cypress.config.ts"
setupNodeEvents(on, config) {
  on('before:spec', () => {
    resetDb();
  });
}
```

If you want to use this plugin in the windowed/interactive version of Cypress, we need to activate an experimental flag. To do so, add the following property to your Cypress configuration:

```ts title="cypress.config.ts"
{
  experimentalInteractiveRunEvents: true,
}
```

I suggest doing it, since running the tests in the interactive mode that updates the DB will most likely fail if you don't reset the database on each test.

Now, go on and run your tests. You should see the database being reset before each test! 🎉 Yay!

## Manually resetting the database in your tests

If you don't want to reset the database before each test, you can also reset the database manually in your tests. 

Let's add a custom Cypress command to do so.

### Writing the Cypress task that will execute the npm script

First, we need to write a Cypress task that will execute the npm script we wrote earlier. 

We will add this next to the `on` event we wrote earlier in `setupNodeEvents`:

```ts title="cypress.config.ts"
setupNodeEvents(on, config) {
  on('task', {
    resetDatabase() {
      return resetDb();
    },
  });
}
```

### Adding a custom Cypress command to reset the database

If you use Typescript, we need to augment the Cypress namespace to add our custom command. Add the snippet below to your global typings file and ensure it's picked up by your `tsconfig.json` file:

```ts
declare global {
  namespace Cypress {
    interface Chainable {
      resetDatabase(): void;
    }
  }
}
```

Now, we can add the command to the `commands.ts` file

```ts title="cypress/support/commands.ts"
Cypress.Commands.add(`resetDatabase`, () => {
  cy.task(`resetDatabase`);
});
```

We can now call `cy.resetDatabase()` in our tests to reset the database. For example, we can add it to the `before` hook of a specific test:

```ts title="cypress/integration/my-test.spec.ts"
describe('My test', () => {
  before(() => {
    cy.resetDatabase();

    // wait for the database to reset
    cy.wait(1000)
  });

  it('should do something', () => {
    // ...
  });
});
```

## Conclusion

In this tutorial, we learned how to reset the Supabase database in Cypress E2E tests. We saw how to write an npm script to reset the database, and how to write a Cypress plugin to reset the database before each test. We also saw how to write a custom Cypress command to reset the database manually in our tests.

If you have any questions, feel free to reach out to us on Discord or Twitter. We're happy to help!

Reset the Supabase Database in Cypress


While Cypress has greatly simplified E2E testing for developers, it can still be tricky at times. For example, a best practice while running E2E testing is bypassing the UI when testing pages behind user authentication. 

The Cypress team, in particular, has long advocated for programmatically authenticating users when testing code not related to the authentication flow.
For example, if you are testing your Dashboard code, there is no need to use the UI to authenticate your users: this will only result in slower, heavier and more flaky E2E tests.

In this post, we show you how to sign in programmatically with Firebase Authentication to improve the speed of your Cypress tests and increase their reliability.

## Adding a Cypress command to sign-in programmatically

Cypress allows us to write global commands that we can access using the `cy` variable, which is globally available in all our Cypress tests.

To do so, we will extend Cypress commands with a new command we will name `signIn`, and will be available to us using `cy.signIn()`. Neat, isn't it?

First of all, we want to play nice with Typescript. That means we extend the Typescript's interface in a filename we name `global.d.ts`:

```tsx title="global.d.ts"
namespace Cypress {
    interface Chainable {
      signIn(
        redirectPath?: string,
        credentials?: { email: string; password: string }
      ): void;
    }
  }
}
```

Now, we can extend Cypress with a custom command named `signIn`. To do so, we add a command using the method `Cypress.Commands.add`:

```tsx title="commands.ts"
Cypress.Commands.add(
  'signIn',
  (
    redirectPath = '/',
    credentials = {
      email: Cypress.env(`EMAIL`) as string,
      password: Cypress.env(`PASSWORD`) as string,
    }
  ) => {
    // body
  }
);
```

The above function takes two parameters:
1. A path where to redirect users after signing in
2. The user credentials, but by providing some default values using environment variables

Let's now write the body of the function:

```tsx
// preserve the session cookie between tests
// otherwise the user will get logged out
Cypress.Cookies.defaults({
  preserve: ['session'],
});

// the function we will define to sign users in
signInProgrammatically(credentials); // <--- implementation is below

// after sign-in, we redirect the users to the provided path
cy.visit(redirectPath);
```

### Signing in using Cypress sessions

If you are using Cypress 12, you will need to use `cy.session`. The `cy.session` command will preserve the session cookie between tests, otherwise, the user will get logged out.

```tsx
Cypress.Commands.add(
  'signIn',
  (
    redirectPath = '/',
    credentials = {
      email: Cypress.env(`EMAIL`) as string,
      password: Cypress.env(`PASSWORD`) as string,
    }
  ) => {
    cy.session([credentials.email, credentials.password],
      () => {
        signInProgrammatically(credentials);
      }
    );

    cy.visit(redirectPath);
  }
);
```

## Using the Firebase Auth SDK to authenticate users in Cypress E2E tests

To sign our testing users in without having to interact with the application's UI, we will use the Firebase SDK.

### Connecting to the Firebase Auth Emulator

Of course, when running tests, we will be connecting to the Firebase Emulator. 

Below is a function `getAuth` that will initialize the Firebase SDK and return an instance of the Firebase Auth SDK connected to the local Firebase Emulator:

```tsx
import {
  Auth,
  connectAuthEmulator,
  initializeAuth,
  signInWithEmailAndPassword,
  UserCredential,
  indexedDBLocalPersistence,
} from 'firebase/auth';

function getAuthEmulatorHost() {
  const host = Cypress.env('NEXT_PUBLIC_FIREBASE_EMULATOR_HOST') as string;
  const port = Cypress.env('NEXT_PUBLIC_FIREBASE_AUTH_EMULATOR_PORT') as string;

  return ['http://', host, ':', port].join('');
}

let auth: Auth;

function getAuth() {
  const app = createFirebaseApp();

  auth =
    auth ||
    initializeAuth(app, {
      persistence: indexedDBLocalPersistence,
    });

  connectAuthEmulator(auth, getAuthEmulatorHost());

  return auth;
}
```

### Signing users in

Now that we can create an instance of the Firebase Auth SDK connected to the emulators, we can use it to sign users in programmatically:

```tsx
export function signInProgrammatically({
  email,
  password,
}: {
  email: string;
  password: string;
}) {
  const auth = getAuth();

  const signIn = signInWithEmailAndPassword(
    auth, 
    email, 
    password
  )
  .catch((e) => {
    cy.log(`User could not sign in programmatically!`);
    console.error(e);
  });

  return cy.wrap(signIn);
}
```

Finally, the `signInProgrammatically` function completes the `cy.signIn()` command defined in the beginning.

## Writing a Test that signs users in programmatically

Whenever you write tests that require users to be signed in, you can write the below:

```tsx
describe(`Create Invite`, () => {
  const email = `invited-member@makerkit.dev`;

  before(() => {
    cy.signIn(`/settings/organization/members`);
  });

  // your tests go here
});
```

As you can see, we can pass any path to the `signIn` function: after signing in, we redirect the users directly to that page, rather than having to use the UI. This will dramatically improve your E2E tests' speed and make them more reliable. Regardless, no need to test the authentication page over and over!

Testing

Tutorials and Guides about Testing

Programmatic Authentication with Supabase and Cypress

Reset the Supabase Database in Cypress

Programmatic Authentication with Firebase and Cypress