Every engineer knows that testing is a “good thing” but many have the same reluctant acceptance as one might have towards eating their vegetables. Attitudes like aiming for 100% code coverage, or going through the motions of writing meaningless unit tests, often don’t do much to improve the actual correctness of a system despite consuming a lot of engineering effort. I’m not going to argue that you test everything on principle, but rather outline concrete steps you can take at various levels of your stack. As a gut-check, I’d suggest looking them over and see which makes sense for your system, making one targeted investment at a time. As I say in the [parent post about operational maturity](https://stack.convex.dev/operational-maturity-for-production), there isn’t a destination where you’ll be “done” with testing. Rather, treat it as an ongoing process that you improve as your app matures. In general I would encourage investment in roughly the order they’re presented.

### Manual testing in development environment

Hopefully you try your code locally before having it reviewed or pushing it to production. This might seem obvious, but there are a few best practices to make this more effective. It helps to actually detail in your commit or pull-request message how you manually tested the change. Adding screenshots or print outs of outputs can be helpful for reviewers to double check that your manual test was indeed successful. It’s also important when iterating on a change to always repeat the full manual test on the latest version of your code. Since manual testing takes a lot of time, you should figure out how to automate at least some form of tests as soon as possible.

### Testing core business logic

The simplest tests assert the basic business behavior of your app. You should start by testing the logic that is core to your value proposition, and anything to do with security or accounting. Encode the guarantees you want the code to make, not just to validate your logic today, but also to catch regressions or accidental changes that may indirectly break a core invariant. For a full-stack app, the backend API is the perfect place to exercise your code and assert its behavior.

Convex comes with a library that mocks the backend running your functions and lets you write tests that execute fast. Fast tests are important so that you can write as many of them as you need, and get a signal back quickly during development and in CI. Check out the [Testing page in Covex docs](https://docs.convex.dev/functions/testing).

## End-to-end testing

### Manual testing on each PR via preview deployments

Preview deployments allow you to test new code in a production-like environment. This is often triggered by creating a branch and pull request on GitHub, and common with frontend hosting providers like [Vercel](https://docs.convex.dev/production/hosting/vercel#preview-deployments) and [Netlify](https://docs.convex.dev/production/hosting/netlify#deploy-previews). This allows reviewers to play around with your code, without checking out your branch and running it locally. If you’re using SSR, ISR, SSG, RSC, or any other frontend optimizations that change how your app is built, this will also help you see that behavior in a more representative environment than a local instance.

With Convex Pro you can also [provision a preview Convex deployment](https://docs.convex.dev/production/hosting/preview-deployments) to have a per-preview backend alongside your preview frontend and test your full-stack app without affecting the data in your production app.

### Adding smoke tests as an end-to-end sanity check

“Smoke” tests are very basic tests to ensure there are no glaring issues. The term comes from testing hardware where simply plugging in a device and checking for smoke can catch mistakes, even if none of the advanced functionality is exercised.

For web apps you can write sophisticated tests using a tool like [Cypress](https://www.cypress.io/) or [Playwright](https://playwright.dev/), but you can also catch a surprising number of bugs from a test that simply loads the page. I’d recommend starting here and expanding browser testing as pages and functionality stabilize.

You can run smoke tests against a local backend.

### Running tests against a local backend

You can spin up a local backend to run tests that go from a client all the way through to the database. Running it locally helps in quickly creating fresh instances to test against, and allows you to scale running these tests without using hosting resources. It won’t catch issues involving your hosted configuration (such as any firewalls between your backend and other resources you might access in tests), for which running tests or manually testing in a hosted backend can help.

[Use the guide here](https://stack.convex.dev/testing-with-local-oss-backend) for running a local open-source Convex backend.

## Testing in production

In addition to tests that run in isolation, there are some places where the thing you are testing is the production ecosystem itself - the hosting, access patterns, unique user behavior, etc.

### Staging deployments

Before you launch your app to everyone, you can deploy to a project that is set up similarly to production, but only serves a subset of users - usually employees, manual user testers, and alpha users. These deployments can happen more frequently than production, such as on every PR merged into `main` or via a daily cron. This allows developers to see their change “live” and catch any bugs they missed in the preview deployment environment.

In Convex you can use a separate project for either the staging or actual production deployment. See [Production page in docs](https://docs.convex.dev/production#staging-environment).

### Liveness checks using Pingdom

[Pingdom](https://www.pingdom.com/) is one of many services that will regularly make dummy requests to your application to help catch when your site goes down. Tests that run within your regular environment, or metrics about your site health can fall short of catching issues like a mis-configured DNS record or VPC. Does your app have no issues because it’s bug free or because no one can access it? It can also help detect when you **aren’t** down, but think you are because of a change in metrics reporting. Having an external service execute a basic request once in a while adds another layer of reassurance and debugging information.

### Data verification via background jobs

Convex is a robust ACID-compliant database with serializable isolation and many great transactional guarantees, but it won’t prevent you from violating your own logical invariants, such as having every user be a member of at least one team. Testing is a layered approach and that layer needs to extend into a running application and verifying that logical invariants are maintained. At scale, some invariants cannot be enforced inside transactions, so you’ll need to periodically verify these asynchronously.

For instance, if you are building a social network, at scale you’ll want to denormalize the number of friends a user has, rather than querying all of their friends when you want to display a count. When you add a friend, you’ll increment their friend count, and when they’re removed, you decrement it. If you change this behavior and introduce a bug, it’s not mission-critical, but it would be good to catch as soon as possible. One way to achieve this is to sanity check the number of friends for all users modified in a mutation. However, this can bloat the transaction and negate the performance benefits of denormalization. A more scalable approach is to routinely walk the data and re-compute derived fields, alerting on any inconsistencies found so a developer can find the bug and patch the incorrect data. These offline checks are not an immediate priority, but are especially helpful as your team grows and data becomes more mission-critical.

### Feature gating risky changes for instant rollbacks

You can ship new features that are gated behind some remotely configured flag, which allows you to deploy the new code and turn on the new feature at different times. You can also use the flag to turn off features that don’t work as intended. When making riskier changes, it’s safer to leave the code around for the older version, and gradually release the newer version, monitoring for regressions. To start you can [achieve this in Convex](https://stack.convex.dev/feature-gating) with a simple “flags” table. As your needs grow to managing cohorts and gradual rollouts, you’ll likely want a product like [LaunchDarkly](https://launchdarkly.com/) which also has tooling for A/B tests. 

# Summary

As your app matures, tests will help you stay sane, and allow you to focus on your product. They come in many shapes and sizes, testing various parts of the stack and anything from business logic to infrastructure configuration. What is the area you feel your app is most vulnerable? Where could you make a small investment with a big potential impact? Pick off one thing at a time and prioritize it against other investments in your app’s operational maturity that you can [read about here](https://stack.convex.dev/operational-maturity-for-production).

Learn about best practices for testing your full-stack apps - running on Convex or elsewhere!

Testing for peace of mind

**Note:** This article was written before we released the [`convex-test`](https://www.npmjs.com/package/convex-test) library along with the [testing guidance](https://docs.convex.dev/functions/testing) to use it for unit tests. We generally recommend writing unit tests using `convex-test` over using a local backend, and [this section](https://docs.convex.dev/functions/testing#testing-using-the-local-backend) lists some of the pros and cons for testing against a local backend.

Convex recently released an [open source version](https://github.com/get-convex/convex-backend) of the backend. We can use this to unit test Convex functions by running them with a local backend. These tests will work by running a backend locally, pushing your code, and using the `ConvexClient` to execute queries and mutations from your favorite testing framework and asserting on the results.

Here’s an [example](https://github.com/get-convex/convex-helpers/blob/main/convex/example.test.ts) of a simple test we might want to write if we were building a notes app:
```ts
  test("can only read own notes", async () => {
    const personASessionId = "Person A";
    await t.mutation(api.notes.add, {
      sessionId: personASessionId,
      note: "Hello from Person A"
    });

    await t.mutation(api.notes.add, {
      sessionId: personASessionId,
      note: "Hello again from Person A"
    });

    const personBSessionId = "Person B";
    await t.mutation(api.notes.add, {
      sessionId: personBSessionId,
      note: "Hello from Person B"
    });

    const personANotes = await t.query(api.notes.list, {
      sessionId: personASessionId
    });
    expect(personANotes.length).toEqual(2);
  });
	```
	
# 	Setting up a local backend
First, we need to make sure we are able to run a local backend by following the instructions [here](https://github.com/get-convex/convex-backend?tab=readme-ov-file#getting-started). Make sure `just run-local-backend` runs successfully.

To make it easier to interact with the local backend from our project, we can add a [`Justfile`](https://github.com/get-convex/convex-helpers/blob/main/Justfile) supporting the following commands: `just run-local-backend`, `just reset-local-backend`, and `just convex [args]` to run Convex CLI commands against the local backend. These can be copied from the open source backend's [`Justfile`](https://github.com/get-convex/convex-backend/blob/main/Justfile).

We want a command like `npm run testFunctions` that does the following:

- Ensures a fresh local backend is running
- Sets the `IS_TEST` environment variable, allowing us to run testing only functions (`just convex env set IS_TEST true`)
- Pushes code to the local backend (`just convex deploy`)
- Runs the tests (e.g. `npx vitest`)
- Finally, tears down the local backend

One way to do this is to write a script, [`backendHarness.js`](https://github.com/get-convex/convex-helpers/blob/main/backendHarness.js), that handles setting up the local backend, runs a command, and finally tears down the backend.

We can add commands to our [`package.json`](https://github.com/get-convex/convex-helpers/blob/main/package.json) that look something like this:
```json
// package.json
"scripts": {
	// Test assuming there's an existing local backend running
	"testFunctionsExistingBackend": "just convex env set IS_TEST true && just convex deploy && vitest",
	// Test handling local backend creation + cleanup
	"testFunctions": "node backendHarness.js 'npm run testFunctionsExistingBackend'"
}
```

# Writing tests
In this set up, all our tests will be running against the same local backend, since running a backend for each test would be too slow. To keep tests isolated from each other, we want to configure our testing framework to run tests one at a time (e.g. `maxWorkers: 1` in [vitest.config.mts](https://github.com/get-convex/convex-helpers/blob/main/vite.config.mts)) and also call a function to clear out all our data after each test.

We’ll add a [clearAll mutation](https://github.com/get-convex/convex-helpers/blob/main/convex/testingFunctions.ts#:~:text=clearAll) that looks something like this:
```ts
export const clearAll = testingMutation(async (ctx) => {
  for (const table of Object.keys(schema.tables)) {
    const docs = await ctx.db.query(table as any).collect();
    await Promise.all(docs.map((doc) => ctx.db.delete(doc._id)));
  }
  const scheduled = await ctx.db.system.query("_scheduled_functions").collect();
  await Promise.all(scheduled.map((s) => ctx.scheduler.cancel(s._id)));
  const storedFiles = await ctx.db.system.query("_storage").collect();
  await Promise.all(storedFiles.map((s) => ctx.storage.delete(s._id)));
})
```
It clears data from all tables listed in the schema, cancels any scheduled jobs, and deletes any stored files. 

The [`testingMutation` wrapper](https://github.com/get-convex/convex-helpers/blob/main/convex/testingFunctions.ts#:~:text=testingMutation) uses [`customMutation`](https://github.com/get-convex/convex-helpers/blob/main/packages/convex-helpers/server/customFunctions.ts) from `convex-helpers` to ensure all functions check that the `IS_TEST` environment variable is set to prevent `clearAll` from being called on Production or Development deployments.

```ts
export const testingMutation = customMutation(mutation, {
  args: {},
  input: async (_ctx, _args) => {
    if (process.env.IS_TEST === undefined) {
      throw new Error(
        "Calling a test only function in an unexpected environment"
      );
    }
    return { ctx: {}, args: {} };
  },
});
```

Putting all of this together, we can write a [test](https://github.com/get-convex/convex-helpers/blob/main/convex/example.test.ts) for our Convex functions which we can run via `npm run testFunctions`:
```ts
import { api } from "./_generated/api";
import { ConvexTestingHelper } from "convex-helpers/testing";

describe("testingExample", () => {
  let t: ConvexTestingHelper;

  beforeEach(() => {
    t = new ConvexTestingHelper();
  });

  afterEach(async () => {
    await t.mutation(api.testingFunctions.clearAll, {});
    await t.close();
  });

  test("can only read own notes", async () => {
    const personASessionId = "Person A";
    await t.mutation(api.notes.add, {
      sessionId: personASessionId,
      note: "Hello from Person A"
    });

    await t.mutation(api.notes.add, {
      sessionId: personASessionId,
      note: "Hello again from Person A"
    });

    const personBSessionId = "Person B";
    await t.mutation(api.notes.add, {
      sessionId: personBSessionId,
      note: "Hello from Person B"
    });

    const personANotes = await t.query(api.notes.list, {
      sessionId: personASessionId
    });
    expect(personANotes.length).toEqual(2);
  });
});
```

A PR setting up tests for a Chess app built on Convex, following this guide, can be found [here](https://github.com/get-convex/convex-chess/pull/19). It includes some examples of [more complex tests](https://github.com/get-convex/convex-chess/blob/main/games.test.ts).

It includes testing authenticated functions (this uses the same mechanism as the dashboard function tester to act as a particular user)
```ts
 const sarahIdentity = t.newIdentity({ name: "Sarah" });
 const asSarah = t.withIdentity(sarahIdentity);
 
 const gameId = await asSarah.mutation(api.games.newGame, {
	 player1: "Me",
	 player2: null,
 });
 let game = await t.query(api.games.get, { id: gameId });
 expect(game.player1Name).toEqual("Sarah");
```

It also uses test only mutations to set up data (setting up a chess game 2 moves from the end):
```ts
// Two moves before the end of the game
const gameAlmostFinishedPgn = "1. Nf3 Nf6 2. d4 Nc6 3. e4 Nxe4" /* ... */

const gameId = await t.mutation(api.testing.setupGame, {
	player1: sarahId,
	player2: leeId,
	pgn: gameAlmostFinishedPgn,
	finished: false,
});
```

# Limitations

Scheduled functions (`ctx.scheduler` and crons) will run in this local backend as time progresses, and while it’s possible to check the state of a scheduled job using [`ctx.db.system`](https://docs.convex.dev/database/advanced/system-tables), there’s no built in way to run a scheduled function for testing or to mock out time and manually advance it in tests.

There is also no built in way to mock out or control randomness in the tested functions.

See the [documentation](https://docs.convex.dev/functions/testing#testing-using-the-local-backend) for a comparison of this testing strategy with unit tests using the [`convex-test`](https://www.npmjs.com/package/convex-test) library.

# Summary

Convex functions can be unit tested using a locally running Convex backend.

Check out [the open source backend](https://github.com/get-convex/convex-backend) or see [an example](https://github.com/get-convex/convex-chess/pull/19) of these tests in action!

Convex recently released an open source version of the backend. We can use this to unit test Convex functions by running them with a local backend. These tests will work by running a backend locally, pushing your code, and using the `ConvexClient` to execute queries and mutations from your favorite testing framework and asserting on the results.

Running tests using a local open-source backend

No one likes to open up a website and see an empty UI. Or worse, to start up a fresh clone of a project to a host of errors because some configuration is expected to be in your brand-new database. Now that [preview deployments](https://docs.convex.dev/production/hosting/preview-deployments) make it easier than ever to test out backend changes, it’s especially helpful to have a fast way to populate a new database instance during development.. How can you bootstrap your project’s data on a fresh install?

In this post we’ll look at some options for “seeding” your database. You can do this when you first create a project, every time you create a preview deployment, or whenever you want to wipe the slate clean and start over. We’ll look at a few different approaches and their pros and cons, and then I’ll share the workflow that I’ve personally found most useful. We’ll be talking about strategies for <QuickConvex />, but the concepts are general.

*Short on time? Feel free to skip ahead to [my personal recommendations](#my-workflow-preference).*

# Three ways to add data to your project

## 1. Manual entry on the dashboard

The most straightforward way to add data to a project is to add it yourself. 

To add data in <QuickConvex />, go to your [dashboard](https://dashboard.convex.dev/), open or create the table you want to populate, and click “Add Documents” to write (or paste) JSON to define your documents. You can add many objects in an array, or one at a time.

In a SQL-based app, this would look like doing manual `INSERT` statements on your tables on the command line.

**Pros:**

- Dead simple, and fast to iterate on without changing contexts. You can go straight from inserting to editing a document in the dashboard.

**Cons:**

- You can only add documents to one table at a time.
- It’s a lot of typing if you aren’t copying them from a file. If you ******are****** copying from a file, see the next section for a faster way.

If you’re the only developer not using [preview deployments](https://docs.convex.dev/production/hosting/preview-deployments) and are infrequently making breaking schema changes, this might be all you need. If not, read on.

## 2. Importing from the CLI

You can use `npx convex import` to add a lot of data at once. If you had an array of JSON objects you were copying into your database using the dashboard, you may as well run this instead. A couple of features to point out:

- The supported data formats are CSV, a JSON array, [a JSONL file](https://jsonlines.org/), or a zip in the format of [`npx convex export`](https://docs.convex.dev/database/import-export/export).
- The command imports data into a single table, or many tables if it's a zip.
- You can pass `--replace` or `--append` if you already have data in that table.
- You have to pass `--prod` to import into the prod DB.
- You can use [`npx convex export`](https://docs.convex.dev/database/import-export/export) to capture a snapshot of data from an app and re-import it without losing any ID references or creation timestamps.

**Pros:**

- You can add a lot of data at once.
- You can skip the “wipe existing data” step if you pass `--replace`.
- You can add documents that have references to each other if you use the zip format.
- You can script it: for previews, you can configure your build command to something like `npx convex deploy --cmd 'npm run build' && npx convex import --table mytable mydata.csv`.

**Cons:**

- If the data doesn’t match your schema, you’re in trouble and will have to edit those data files. If you have schema validation on, the `npx convex import` command will fail (thank you schema validation!). If you have schema validation off (or haven’t specified a schema at all), your app may break when it starts working with the data in the wrong shape.

If you have simple database tables that need to be configured with dynamic data available, this might be your ticket. You can produce CSV, JSON, or zip files as part of a build step, then import them after deploying your code. Reach out to us on [Discord](https://convex.dev/community) if you want support on more complicated setups.

## 3. Seeding data in code

Why not insert data the same way you would when running your app? Using the same APIs and sharing the same helpers? Here’s how it works:

- In Convex, you write data to the database in a [mutation](https://docs.convex.dev/functions/mutation-functions)[^1].
- You can call mutations from the Dashboard, or from the CLI with from the CLI with one of these commands:
    - `npx convex run` if you just want to run the command once.
    - `npx convex dev --run` if you want to run it and continuously sync code changes to your development deployment.
    - `npx convex deploy --preview-run` if you want to run the command on a new [preview deploy](https://docs.convex.dev/production/hosting/preview-deployments).
- You can configure your [`package.json` scripts](https://docs.npmjs.com/cli/v10/using-npm/scripts) to run these commands automatically, so you merely run `npm run dev` to both start your app and seed your data.
- If you need to access 3rd party services to get seed data, you can! You can have the function run an [action](https://docs.convex.dev/functions/actions), which can [call mutations](https://docs.convex.dev/functions/actions#action-context) after fetching data from an API.
- Related: see [this post](https://stack.convex.dev/generating-fake-data) for tips on using Faker.js which helps avoid naming fatigue and find bugs.

**Pros:**

- The data can reference the same types you use in your code and database schema, so as things change, your seed scripts stay up to date automatically. Otherwise seed data has a bad habit of getting out of sync with the latest database schema.
- You can re-use helpers to create documents, both in seed data and in your production code. This can keep those codepaths well-used.
- You can have multiple seed scripts that you call from different contexts, for instance setting up dummy data for previews, data with edge cases for tests, and so on.

**Cons:**

- You have to write code, and keep it up to date.
- If you want to import a lot of data, your mutation will need to import that file server-side, where it runs. If this is a lot of data, it can slow down deployment.

This is my favored approach, and the one I generally use when building new Convex apps. In particular, I have the action or mutation as the default export in `convex/init.ts` so I can refer to it on the CLI as merely `init`: `npx convex run init`.

[^1]: **Note** you should use an [`internalMutation`](https://docs.convex.dev/functions/internal-functions) here, to prevent any public client from calling your mutation. You can still run them with `npx convex run myFile:myInternalMutation`, `npx convex dev --run myFile:myInternalMutation`, or `npx convex deploy --cmd 'npm run build' --preview-run myFile:myInternalMutation`.

## My workflow preference

In my projects I like to configure “seed” data in code. It can be type-checked against the latest schema and scripted to produce complicated structures. 

- In my Convex project, I have a default export in `convex/init.ts` that is either a [mutation](https://docs.convex.dev/functions/mutation-functions) or an [action](https://docs.convex.dev/functions/actions). Running it adds data, or returns if data has already been added, making it safe to call many times. Use an [`internalMutation`](https://docs.convex.dev/functions/internal-functions) here, to prevent any public client from calling your mutation.
- In `package.json` I configure my [scripts](https://docs.npmjs.com/cli/v10/using-npm/scripts) to call the `init` function when first running `npm run dev` with `convex dev --run init`: full scripts setup can be seen [here](https://github.com/get-convex/convex-tour-chat/blob/main/package.json#L9).
- For [preview deploys](https://docs.convex.dev/production/hosting/preview-deployments), I set the build command to be `npx convex deploy --cmd 'npm run build' --preview-run init`.
- When making a breaking change to the schema, I make the change, update the `init` function (usually just chasing down TypeScript errors), clear tables, and re-initialize.

# Summary

Storing seed data is useful for adding configuration data, dummy data for previews or during development, and more. We looked at three ways of seeding data, and you can look forward to more ways coming in the future 🤫. If you want to continue the discussion, come [join us in Discord](https://convex.dev/community)! 

Now that we've launched Preview Deployments on Convex, you can test out backend changes easier than ever. But you may want to seed your project with data first, so let's go over how to do that.

Seeding Data for Preview Deployments

Are you setting up a new development environment and would like to fill it with sample data instead of it being empty? Or perhaps you want to make sure that your UI looks good when you have more than a few rows in your database?

You could create many rows by yourself, but it is tedious if you want good-looking and numerous results. In this article, we’re going to discover a much better way to seed your database with sample data.

# Install Faker
We’re going to use a library called [Faker](https://fakerjs.dev). It provides helpful functions to generate realistic values in large quantities.

Before we begin, make sure you have a <QuickConvex /> project set up on your machine. If you don't have one already, you can create one using the [Quickstart guide](https://docs.convex.dev/quickstarts).

Then, install Faker using the following command:
```bash
npm install @faker-js/faker
```

# Create an Internal Mutation
I will start by creating a new mutation in my Convex app by writing the following code in a file named `convex/users.ts`:
```typescript
import { internalMutation } from "./_generated/server";

export const createFake = internalMutation(async (ctx) => {
  // …
});
```

Marking the mutation as internal ensures that users of my app can’t call it. I will still be able to call it myself from the dashboard or [the Convex command-line tool](https://docs.convex.dev/cli#run-convex-function).

# Insert Fake Data
Now, we’re ready to start inserting data. You can consult the [Faker documentation](https://fakerjs.dev/api/) to know which data types it can generate:

![The Faker documentation.](https://cdn.sanity.io/images/ts10onj4/production/d0905e01d05b33fcc1dda0f8350d644ea0691e9d-2626x1978.png?w=1400 "The Faker documentation.")

For my project, I need a list of users that each have a name, a company, and an avatar. I will use the corresponding types to create 200 new users:

```typescript
import { faker } from '@faker-js/faker';
import { internalMutation } from "./_generated/server";

export const createFake = internalMutation(async (ctx) => {
  // Initialize Faker with a random value
  faker.seed();

  for (let i = 0; i < 200; i++) {
    await ctx.db.insert("users", {
      name: faker.person.fullName(),
      company: faker.company.name(),
      avatar: faker.image.avatar(),
    });
  }
});
```

In the beginning of the function, we call `faker.seed()` so that Faker generates different data each time we call our function. We need it because Faker initializes its random number generator statically. When using Convex, this will happen every time you push new code, not every time you call a function.

Now that we’ve written our function, we can run it using `npx convex run` in the command line. You can also run it [from the Convex dashboard](https://docs.convex.dev/dashboard/deployments/functions#running-functions) instead.
```
npx convex run users:createFake
```

When opening my `users` table [in the Convex dashboard](https://docs.convex.dev/dashboard/deployments/data), I can see that I’ve successfully created 200 new users:

![My fake users in the dashboard.](https://cdn.sanity.io/images/ts10onj4/production/7b481bcc5fdb38b5e2bfd4a5310711081b3e66c7-3246x1744.png?w=1400 "My fake users in the dashboard.")

And when opening my app, I can see that not only do I see all my fake users, but also that they all have avatars!

![The new users in my sample app.](https://cdn.sanity.io/images/ts10onj4/production/c88cf6d5486033191c9be6aba3017901ae951a16-2538x1564.png?w=1400 "The new users in my sample app.")
# Summary
We’ve seen how to create fake data using the Faker library and use it to create rows in the Convex database. To learn more advanced ways to generate fake data, you can read [the Faker documentation](https://fakerjs.dev/api/).


Learn how to generate fake data for your dev deployments using the Faker library

Testing Your App: How to Generate Fake Data

Oftentimes during testing we want to mock out our backend so we can unit test our UI components without talking to our actual server code.

In this article, we’ll explore options for testing React components that call Convex React hooks using mocking and dependency injection. To do this, I’ve written a sample TypeScript React app using the [Vitest](https://vitest.dev) testing framework. The patterns presented in this post are also applicable to JavaScript apps and other frameworks.

Here, we have a React component that renders a counter value stored in Convex, and provides a button for incrementing the counter value by one.

```typescript
// See the full file here:
// https://github.com/get-convex/convex-helpers/blob/main/src/components/Counter.tsx

const Counter = () => {
  const counter =
    useQuery(api.counter.getCounter, { counterName: "clicks" }) ?? 0;    
  const incrementByOne = useCallback(
    () => increment({ counterName: "clicks", increment: 1 }),
    [increment]
  );

  return (
    <div>
      <p>
        {"Here's the counter:"} {counter}
      </p>
      <button onClick={incrementByOne}>Add One!</button>
    </div>
  );
};

export default Counter;
```

<details>
<summary>Convex function details...</summary>

```typescript
// See the full file here:
// https://github.com/get-convex/convex-helpers/blob/main/convex/counter.ts

import { query } from "./_generated/server";
import { mutation } from "./_generated/server";

const getCounter = query(
  async ({ db }, { counterName }: { counterName: string }): Promise<number> => {
    const counterDoc = await db
      .query("counter_table")
      .filter((q) => q.eq(q.field("name"), counterName))
      .first();
    return counterDoc === null ? 0 : counterDoc.counter;
  }
);

const incrementCounter = mutation(
  async (
    { db },
    { counterName, increment }: { counterName: string; increment: number }
  ) => {
    const counterDoc = await db
      .query("counter_table")
      .filter((q) => q.eq(q.field("name"), counterName))
      .first();
    if (counterDoc === null) {
      await db.insert("counter_table", {
        name: counterName,
        counter: increment,
      });
    } else {
      counterDoc.counter += increment;
      await db.replace(counterDoc._id, counterDoc);
    }
  }
);

export { getCounter, incrementCounter };
```

</details>



Let’s write a test to make sure this component renders the value returned from the query above. Later, we can add more tests, such as ensuring that clicking on the button calls the desired mutation (as seen in the full examples linked in the snippets later in this article).

```typescript
import Counter from "./Counter";
import { render } from "@testing-library/react";
import { describe, it, expect, vi } from "vitest";

const setup = () => render(<Counter />);

describe("Counter", () => {
  it("renders the counter", async () => {
    const { getByText } = setup();
    expect(getByText("Here's the counter: 0")).not.toBeNull();
  });
});
```

But wait! This test doesn’t work yet. Since the Counter component invokes Convex queries and mutations, we need some mechanism to replace our Convex functions with fake implementations. If we try to run this test file without doing so, we’ll get an error with the Convex library complaining that a Convex client has not been provided.

## Method 1: Mocking the convex import

This method takes advantage of Vitest’s mock to replace the internal `useQuery` and `useMutation` implementations with versions that call our fake methods defined in the previous code snippet.

```typescript
// See the full file here:
// https://github.com/get-convex/convex-helpers/blob/main/src/components/Counter.mock.test.tsx

import * as convexReact from "convex/react";

vi.mock("convex/react", async () => {
  const actual = await vi.importActual<typeof convexReact>("convex/react");

  return {
    ...actual,

    // Not a typo! useQuery in code calls useQueryGeneric under the hood!
    useQueryGeneric: (queryName: string, args: Record<string, any>) => {
      if (queryName !== "counter:getCounter") {
        throw new Error("Unexpected query call!");
      }
      return getCounter(args as any);
    },
    useMutationGeneric: (mutationName: string) => {
      if (mutationName !== "counter:incrementCounter") {
        throw new Error("Unexpected mutation call!");
      }
      return incrementCounterMock;
    },
  };
});
```

This method requires few dependencies, but may not work in test environments that don’t provide functionality for mocking external libraries. Read on for a cleaner solution!

## Method 2: Using dependency injection to replace the Convex client

Alternatively, we can use dependency injection (AKA having dependencies be arguments to a function, and passing in a different dependency in test vs. our real codebase) to convince the Convex library it’s connected to a real deployment. 

We’ve prepared a version of the `ConvexReactClient` for testing purposes. The code and TypeScript bindings for `ConvexReactClientFake` can be found [here](https://github.com/get-convex/convex-helpers/tree/main/src/fakeConvexClient).

```typescript
// See the full file here:
// https://github.com/get-convex/convex-helpers/blob/main/src/components/Counter.injection.test.tsx

// Initialize the Convex mock client
const fakeClient = new ConvexReactClientFake<API>({
  queries: {
    // Replace getCounter with a simple function that returns a global value
    "counter:getCounter": getCounter,
  },
  mutations: {
    // Replace incrementCounter with a mocked function that can be spied on in tests
    "counter:incrementCounter": incrementCounterMock,
  },
});

// The setup function is different here -- we wrap the Counter in a ConvexProvider
const setup = () =>
  render(
    <ConvexProvider client={fakeClient}>
      <Counter />
    </ConvexProvider>
  );
```

In summary, you can use one of the patterns above to write unit tests for React components that call Convex functions. 

Have a use case that isn’t covered here? Reach out to us on the [Convex community discord](https://convex.dev/community).

Oftentimes during testing we want to mock out our backend so we can unit test our UI components without talking to our actual server code.

In this article, we’ll explore options for testing React components that call Convex React hooks using mocking and dependency injection. To do this, I’ve written a sample TypeScript React app using the Vitest testing framework. The patterns presented in this post are also applicable to other JavaScript apps and frameworks.