# Trigger.dev CLI E2E suite

E2E test suite for the Trigger.dev v3 CLI.

Note: this only works with Trigger.dev v3 projects and later. There is no E2E test suite for the [@trigger.dev/cli](https://www.npmjs.com/package/@trigger.dev/cli) package yet.

Trigger.dev is an open source platform that makes it easy to create event-driven background tasks directly in your existing project.

## Description

This suite aims to test the outputs fo the `triggerdev deploy` command.
To do so, it runs the deploy code against fixture projects that are located under `packages/cli-v3/e2e/fixtures/`.
Those fixtures reproduce minimal project structure and contents, in order to reproduce known bugs and run fast.

**Notes**
- The suite uses vitest
- Everything happens locally
- There is no login required
- There is not real project reference needed
- No docker image is created or built, instead, the bundled worker file is started with node directly inside the vitest process

## Usage

If you have not done it yet, build the CLI:

```sh
pnpm run build --filter trigger.dev
```

Then, run the v3 CLI E2E test suite:

```sh
pnpm --filter trigger.dev run test:e2e
```

| Option                 | Description                                                                  |
| ---------------------- | ---------------------------------------------------------------------------- |
| `MOD=<fixture-name>`   | The name of any folder directly nested under `packages/cli-v3/e2e/fixtures/` |
| `PM=<package-manager>` | The package manager to use. One of `npm`, `pnpm`, `yarn`. Defaults to `npm`  |

Example:

```sh
MOD=server-only PM=yarn pnpm --filter trigger.dev run test:e2e
```

This will run the test suite for the `server-only` fixture using `yarn` to install and resolve dependencies.

## Debugging

When debugging an issue with the `triggerdev deploy` or `triggerdev dev` command, it is recommended to reproduce it with a minimal project fixture in the e2e suite.
Check [Adding a fixture](#adding-a-fixture) for more information.

Then run:

```sh
MOD=<fixture-name> pnpm run test:e2e
```

This will test your fixture project, and generate outputs in the `packages/cli-v3/e2e/fixtures/<fixture-name>/.trigger` folder, so you can easily debug.

## Adding a fixture

1. Create a new `packages/cli-v3/e2e/fixtures/<fixture-name>` folder.

    It will hold the project to test.

2. Add a `package.json` file in your `packages/cli-v3/e2e/fixtures/<fixture-name>` folder.

    Use the following template:

    ```json package.json
    {
      "name": "<fixture-name>",
      "private": true,
      "engines": {
        "pnpm": "8.15.5",
        "yarn": "4.2.2"
      },
      "packageManager": "pnpm@8.15.5"
    }
    ```

    > The `engines` field is used to store the versions of pnpm and yarn to use when running the suite.

3. Add an empty `pnpm-workspace.yaml` in your `packages/cli-v3/e2e/fixtures/<fixture-name>` folder.

    This is necessary to prevent the Trigger.dev monorepo from handling this project.
    Please check https://github.com/pnpm/pnpm/issues/2412 for more inforation.

4. Add an empty `yarn.lock` in your fixture folder.

    This is necessary to allow to use `yarn` without having a warning on the current project being a `pnpm` project.

5. Add the following `.yarnrc.yaml` in your fixture folder.

    This will avoid having `.pnp.cjs` and `.pnp.loader.mjs` and keep versioned files to a minimum.

    ```yaml .yarnrc.yml
    nodeLinker: node-modules
    ```

6. Install the fixture dependencies and generate lockfiles.

    Like you would in any project.
    E.g. if your fixture contains a trigger task that uses the `jsdom` library:

    ```sh
    cd packages/cli-v3/e2e/fixtures/<fixture-name>
    corepack use pnpm@8.15.5
    pnpm install jsdom
    ```

    > This will update the `package.json` and generate the `pnpm-lock.yaml` file.

7. To run the test suite against multiple package manager, we need to generate the other lockfiles.

    ```sh
    cd packages/cli-v3/e2e/fixtures/<fixture-name>
    rm -rf **/node_modules
    npm install
    rm -rf **/node_modules
    corepack use yarn@4.2.2 # will update the yarn lockfile
    ```

    > Do it in this order, otherwise `npm install` will update the existing `yarn.lock` file with legacy version 1.

8. Create a new `packages/cli-v3/e2e/fixtures/trigger` folder, and create a trigger task in it.

    Here is an example:

    ```javascript
    import { task } from "@trigger.dev/sdk/v3";

    export const helloWorldTask = task({
      id: "hello-world",
      run: async (payload) => {
        console.log("Hello, World!", payload);
      },
    });
    ```

9.  Add a trigger configuration file.

    The configuration file is mandatory here, the E2E suite does not execute `trigger.dev` commands.

    ```javascript
    export const config = {
      project: "<fixture-name>",
      triggerDirectories: ["./trigger"],
    };
    ```

    > The project reference can be anything here, as the suite runs locally without connecting to the platform.

10. Commit your changes.

11. Add your fixture test configuration in `fixtures.config.js`.

    ```javascript fixtures.config.js
    export const fixturesConfig = [
      // ...
      {
        id: "<fixture-name>",
      },
      // ...
    ];
    ```

    > You might expect a specific error for a specific test, so use those configuration option at your discretion.
