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!

Programmatic Authentication with Firebase and Cypress


Testing is a crucial part of software development, but it can be difficult to know where to start, especially if you are interacting with the code of a third party on a different application; as it turns out, this is the case with Stripe, the most famous payment processor for developers.

Unfortunately, from what I've seen around, it's very hard to test its implementation, especially if you are using Stripe Checkout, a hosted portal that lives on Stripe's platform.

## Testing external pages with Cypress can be challenging

Why is it hard, you ask?

- Testing applications you do not own is very risky because the code can change anytime and without warning
- Testing real applications can be very time-consuming

Long story short, the Cypress team discourages testing other applications and instead recommends mocking or programmatically interacting with the third party, which is what we'll be doing.

## Testing your Stripe implementation is crucial

Testing your Stripe implementation is crucial to making sure your payments are being processed as intended. If you're building a website, it's best to test out the functionality early and often.

Skipping testing your Stripe may be tempting due to its complexity, and the fact that the Stripe Checkout portal actually does most of the heavy lifting, but it's not something we'd recommend for such a crucial part of your SaaS.

## We assume you have already a working implementation

This guide assumes you have already a working implementation of Stripe in your application.

For this article, I'll show how we can test three scenarios:

- **Creating a subscription**
- **Deleting a subscription**

But first, we have to run a Stripe emulator to mock the calls to the Stripe backend.

## Install stripe-mock, an official library to emulate a Stripe server locally

Stripe has released `stripe-mock`, an official library to **emulate a Stripe server locally**, it will allow you to run your tests against the mocked API and make sure that the changes you've made don't break anything.

To run it, we can use Docker with the following command:

```
docker run --rm -it -p 12111-12112:12111-12112 stripe/stripe-mock:latest
```

The server will run at `localhost:12111` for HTTP and `localhost:12112` for HTTPS.

Additionally, you need to make sure to be running the Stripe CLI server with the following command:

```
stripe listen --forward-to localhost:3000/api/stripe/webhook
```

Of course, remember to update the command with your application's details.

### Stripe Emulator Limitations

The above is amazing, isn't it?

Well, yes, but you should be aware of the limitations of the library:

- **it's stateless**: what does it mean? It does not store the data we create, which means we need to stick to the data that has been preloaded.
- **no webhooks**: it does not automatically send webhooks, which means we have to do it manually.
- **does not cover the full API**: it does not handle the full API, and it only works with the latest version's specs

This is not great, but we can make it work.

## Changing your Stripe instance to work with the emulator

Now that the Stripe server is running, we have to update the Stripe client's to be pointing to the emulator's server, rather than the real Stripe endpoints.

To do so, we also need to discriminate between a production instance and a testing one. Of course, this will depend on how you structured your application; in our case, we use a simple check (the below is based on a Next.js application)

- we check if the `NODE_ENV` variable is `"development"`
- we check if the `NEXT_PUBLIC_EMULATOR` variable is `"true"`

```tsx
function isCypressEnv() {
  return Boolean(
    process.env.NODE_ENV === `development` &&
      process.env.NEXT_PUBLIC_EMULATOR === `true`
  );
}
```

The Stripe emulator instance is created in the following way.

### Loading the Stripe client

1) First, we lazy load the Stripe client library to reduce the API execution time:

```tsx
async function loadStripe() {
  const { default: Stripe } = await import('stripe');

  return Stripe;
}
```

### Initialize the Stripe emulator

Then, we initialize the Stripe emulator instance by passing the correct host and port and changing the protocol to `http` (if you run localhost with HTTPS, feel free to ignore it)

```tsx
async function getStripeEmulatorInstance() {
  const Stripe = await loadStripe();

  return new Stripe(`sk_test_12345`, {
    host: `localhost`,
    port: 12111,
    apiVersion: STRIPE_API_VERSION,
    protocol: `http`,
  });
}
```
Finally, we export a factory that passes the correct instance based on the environment:

```tsx
export async function getStripeInstance() {
  if (isCypressEnv()) {
    console.warn(`Stripe is running in Testing mode`);

    return getStripeEmulatorInstance();
  }

  return getStripeProductionInstance();
}
```
And that's it! All our code that calls the **Stripe API will now interact with the emulator instance** rather than the real Stripe endpoints.

## Creating a Stripe Page Object in Cypress

I'm old-fashioned, so I create page objects in my Cypress tests.

The code below is a small utility to help us write tests more declaratively and in a more reusable fashion:

```tsx
import * as StripeLib from 'stripe';
import { StripeWebhooks } from '~/core/stripe/stripe-webhooks.enum';

const stripe = new StripeLib.Stripe(`sk_test_12345`, {
  host: `localhost`,
  port: 12111,
  apiVersion: '2020-08-27',
  protocol: `http`,
});

const $get = cy.cyGet.bind(cy);
const PORT = 12111;

const stripePo = {
  $plans: () => $get('subscription-plan'),
  $checkoutForm: () => $get('checkout-form'),
  $subscriptionName: () => $get('subscription-name'),
  createWebhookPayload,
  sendWebhook(params: { type: StripeWebhooks; body: UnknownObject }) {
    const body = this.createWebhookPayload(params.body, params.type);
    const signature = stripePo.createSignature(body);

    cy.request({
      url: 'http://localhost:3000/api/stripe/webhook',
      method: `POST`,
      headers: {
        ['stripe-signature']: signature,
      },
      body,
    });
  },
  selectPlan(number: number = 0) {
    this.$plans().eq(number).click();
    this.$checkoutForm().submit();
  },
  createSignature(payload: unknown) {
    return stripe.webhooks.generateTestHeaderString({
      payload: JSON.stringify(payload),
      secret: Cypress.env('STRIPE_WEBHOOK_SECRET'),
    });
  },
};

function createWebhookPayload(data: unknown, type: StripeWebhooks) {
  return {
    id: 'evt_1LK3nDI1i3VnbZTqgFqyzkWx',
    object: 'event',
    api_version: '2020-08-27',
    created: 1657473579,
    data: {
      object: data,
    },
    livemode: false,
    pending_webhooks: 0,
    request: {
      id: null,
      idempotency_key: null,
    },
    type,
  };
}

export default stripePo;
```

Most of it is quite simple if you're not new to Cypress, but you may want to check out the snippet where we send Webhooks to our Stripe endpoint, which can help you write more tests if your code handles more scenarios.

## Sending Webhooks to our Stripe endpoint manually

Makerkit implements a webhook handler at `/api/stripe/webhook.ts` that responds to the event sent by Stripe:

```tsx
switch (event.type) {
  case StripeWebhooks.Completed: {
    // handle Completed
  }

  case StripeWebhooks.AsyncPaymentSuccess: {
    // handle SubscriptionDeleted
  }

  case StripeWebhooks.SubscriptionDeleted: {
    // handle SubscriptionDeleted
  }

  case StripeWebhooks.SubscriptionUpdated: {
    // handle SubscriptionUpdated
    break;
  }

  case StripeWebhooks.PaymentFailed: {
    // handle PaymentFailed
  }
}
```

That means, to send a webhook that targets one of the code paths below (for example, the `Completed` event), **we would do the following request**:

```tsx
stripePo.sendWebhook({
  body: session,
  type: StripeWebhooks.Completed,
});
```

The request above (as you can see from the page object snippet), uses Cypress' `cy.request` to send an HTTP request to our endpoint. By doing so, we emulate the Stripe client:
- instead of having the Stripe emulator run the webhooks requests (which cannot do), **we send them manually with Cypress**
- the tricky part is sending the data with the correct payloads, which **requires work and changing the fixture's data according to both our database's data and the Stripe emulator's static data** (remember, it's stateless! data won't change, and we cannot use our own)
  - fortunately, we provide the `gists` at the end of the article that you can use with your tests

Where does `session` come from? I took them from the mock server's data: because it's static, we are forced to use the same as the server's to make it work.

To load them, we use a `Cypress fixture`, i.e. a piece of data we can load from the `fixtures` folder:

```tsx
cy.fixture('session').then((session) => {
 // session is the JSON stored in the file fixtures/session.json
});
```

## 1) Testing the creation of a Stripe subscription

Let's implement the first scenario, i.e. creating a simple Stripe subscription with immediate payment.

What we are going to do:

- send the webhook above
- verify the UI works
  - in our case, we verify is the subscription has been displayed
    - it's very important to reload your page using `cy.reload()` if you don't update your UI in real-time to see the changes
  - if you want to take it a step further, you could check if the DB's data matches the UI

Let's take a look below:

```tsx
import stripePo from '../../support/stripe.po';
import { StripeWebhooks } from '~/core/stripe/stripe-webhooks.enum';

describe(`Create Subscription`, () => {
  before(() => {
    cy.signIn(`/settings/subscription`);
  });

  describe('Using Webhooks', () => {
    describe(`When the user creates a subscription`, () => {
      before(() => {
        cy.fixture('session').then((session) => {
          stripePo.sendWebhook({
            body: session,
            type: StripeWebhooks.Completed,
          });
        });
      });

      it(`should display a Subscription Card`, () => {
        cy.reload();

        stripePo.$subscriptionName().should('have.text', 'Testing Plan');
      });
    });
  });
});
```

## 2) Testing the deletion of a Stripe subscription

The implementation is very similar to the above, with the exception that we pass:

- the `subscription` fixture instead of `session`
- the event type `StripeWebhooks.SubscriptionDeleted`

```tsx
describe(`When the user unsubscribes`, () => {
  before(() => {
    cy.fixture('subscription').then((subscription) => {
      stripePo.sendWebhook({
        body: subscription,
        type: StripeWebhooks.SubscriptionDeleted,
      });
    });
  });

  it('should delete the subscription', () => {
    cy.reload();

    stripePo.$subscriptionName().should('not.exist');
  });
});
```

## Demo: testing Stripe with Cypress

Here is a short video of the Stripe E2E tests with Cypress that are included in Makerkit:

<Video src='/assets/images/posts/e2e-stripe.mp4' />

It's **fast**, isn't it?

## The fixtures

If you want, you can check out the Stripe fixtures I use for my tests in the `gists` below:

[Click here to download the Subscription and Session gists](https://gist.github.com/Gbuomprisco/3a0969ef9cf82d2b79c6e018a983b964)

Edit the fixtures for your own data:

- for example, `client_reference_id` in `subscription.json` is my own testing organization: you should edit this value to match your database's.

## Conclusion

Testing Stripe with Cypress is a great way to ensure that your payment form, including the callbacks and server-side validation, is working as expected.

I hope the guide above can help you write your Stripe tests with ease and confidence.

Too bothered to write the code yourself? If you purchase Makerkit, it's already done for you!

If you want to give it a try and need a hand, please contact me at [info@makerkit.dev](mailto:info@makerkit.dev); always happy to help!


Cypress

Tutorials and Guides about Cypress

Programmatic Authentication with Supabase and Cypress

Reset the Supabase Database in Cypress

Programmatic Authentication with Firebase and Cypress

How to test Stripe Checkout with Cypress