Skip to content

Commit a938349

Browse files
codenemcodenem
committed
Add a readme file
1 parent 8abd4cf commit a938349

File tree

3 files changed

+192
-20
lines changed

3 files changed

+192
-20
lines changed

‎packages/cli-v3/e2e/README.md

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
# Trigger.dev CLI E2E suite
2+
3+
E2E test suite for the Trigger.dev v3 CLI.
4+
5+
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.
6+
7+
Trigger.dev is an open source platform that makes it easy to create event-driven background tasks directly in your existing project.
8+
9+
## Description
10+
11+
This suite aims to test the outputs fo the `triggerdev deploy` command.
12+
To do so, it runs the deploy code against fixture projects that are located under `packages/cli-v3/e2e/fixtures/`.
13+
Those fixtures reproduce minimal project structure and contents, in order to reproduce known bugs and run fast.
14+
15+
**Notes**
16+
- The suite uses vitest
17+
- Everything happens locally
18+
- There is no login required
19+
- There is not real project reference needed
20+
- No docker image is created or built, instead, the bundled worker file is started with node directly inside the vitest process
21+
22+
## Usage
23+
24+
If you have not done it yet, build the CLI:
25+
26+
```sh
27+
pnpm run build --filter trigger.dev
28+
```
29+
30+
Then, run the v3 CLI E2E test suite:
31+
32+
```sh
33+
pnpm --filter trigger.dev run test:e2e
34+
```
35+
36+
| Option | Description |
37+
| ---------------------- | ---------------------------------------------------------------------------- |
38+
| `MOD=<fixture-name>` | The name of any folder directly nested under `packages/cli-v3/e2e/fixtures/` |
39+
| `PM=<package-manager>` | The package manager to use. One of `npm`, `pnpm`, `yarn`. Defaults to `npm` |
40+
41+
Example:
42+
43+
```sh
44+
MOD=server-only PM=yarn pnpm --filter trigger.dev run test:e2e
45+
```
46+
47+
This will run the test suite for the `server-only` fixture using `yarn` to install and resolve dependencies.
48+
49+
## Debugging
50+
51+
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.
52+
Check [Adding a fixture](#adding-a-fixture) for more information.
53+
54+
Then run:
55+
56+
```sh
57+
MOD=<fixture-name> pnpm run test:e2e
58+
```
59+
60+
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.
61+
62+
## Adding a fixture
63+
64+
1. Create a new `packages/cli-v3/e2e/fixtures/<fixture-name>` folder.
65+
66+
It will hold the project to test.
67+
68+
2. Add a `package.json` file in your `packages/cli-v3/e2e/fixtures/<fixture-name>` folder.
69+
70+
Use the following template:
71+
72+
```json package.json
73+
{
74+
"name": "<fixture-name>",
75+
"private": true,
76+
"engines": {
77+
"pnpm": "8.15.5",
78+
"yarn": "4.2.2"
79+
},
80+
"packageManager": "[email protected]"
81+
}
82+
```
83+
84+
> The `engines` field is used to store the versions of pnpm and yarn to use when running the suite.
85+
86+
3. Add an empty `pnpm-workspace.yaml` in your `packages/cli-v3/e2e/fixtures/<fixture-name>` folder.
87+
88+
This is necessary to prevent the Trigger.dev monorepo from handling this project.
89+
Please check https://github.com/pnpm/pnpm/issues/2412 for more inforation.
90+
91+
4. Add an empty `yarn.lock` in your fixture folder.
92+
93+
This is necessary to allow to use `yarn` without having a warning on the current project being a `pnpm` project.
94+
95+
5. Install the fixture dependencies and generate lockfiles.
96+
97+
Like you would in any project.
98+
E.g. if your fixture contains a trigger task that uses the `jsdom` library:
99+
100+
```sh
101+
cd packages/cli-v3/e2e/fixtures/<fixture-name>
102+
corepack use [email protected]
103+
pnpm install jsdom
104+
```
105+
106+
> This will update the `package.json` and generate the `pnpm-lock.yaml` file.
107+
108+
6. To run the test suite against multiple package manager, we need to generate the other lockfiles.
109+
110+
```sh
111+
cd packages/cli-v3/e2e/fixtures/<fixture-name>
112+
rm -rf node_modules
113+
npm install
114+
rm -rf node_modules
115+
corepack use yarn # will update the yarn lockfile
116+
```
117+
118+
> Do it in this order, otherwise `npm install` will update the existing `yarn.lock` file with legacy version 1.
119+
120+
7. Create a new `packages/cli-v3/e2e/fixtures/trigger` folder, and create a trigger task in it.
121+
122+
Here is an example:
123+
124+
```javascript
125+
import { task } from "@trigger.dev/sdk/v3";
126+
127+
export const helloWorldTask = task({
128+
id: "hello-world",
129+
run: async (payload) => {
130+
console.log("Hello, World!", payload);
131+
},
132+
});
133+
```
134+
135+
8. Add a trigger configuration file.
136+
137+
The configuration file is mandatory here, the E2E suite does not execute `trigger.dev` commands.
138+
139+
```javascript
140+
export const config = {
141+
project: "<fixture-name>",
142+
triggerDirectories: ["./trigger"],
143+
};
144+
```
145+
146+
> The project reference can be anything here, as the suite runs locally without connecting to the platform.
147+
148+
9. Commit your changes.
149+
150+
10. Add your fixture test configuration in `testCases.json`.
151+
152+
```json testCases.json
153+
[
154+
...
155+
{
156+
"name": "<fixture-name>",
157+
},
158+
...
159+
]
160+
```
161+
162+
You can configure your test case by adding other properties to the JSON object. Here is the `TestCase` type for reference:
163+
164+
```typescript
165+
type TestCase = {
166+
name: string;
167+
skipTypecheck?: boolean;
168+
wantConfigNotFoundError?: boolean;
169+
wantBadConfigError?: boolean;
170+
wantCompilationError?: boolean;
171+
wantWorkerError?: boolean;
172+
wantDependenciesError?: boolean;
173+
wantInstallationError?: boolean;
174+
};
175+
```
176+
177+
> You might expect a specific error at a specific test, so use those configuration option at your discretion.

‎packages/cli-v3/e2e/index.test.ts

Lines changed: 5 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,18 @@
11
import { execa, execaNode } from "execa";
2+
import { readFileSync } from "node:fs";
23
import { mkdir, rename, rm } from "node:fs/promises";
34
import { join, resolve } from "node:path";
45

5-
import { Loglevel, LogLevelSchema, PackageManagerSchema } from "./schemas";
66
import { typecheckProject } from "../src/commands/deploy";
77
import { readConfig, ReadConfigFileResult } from "../src/utilities/configFiles";
88
import { PackageManager } from "../src/utilities/getUserPackageManager";
99
import { logger } from "../src/utilities/logger";
1010
import { compile } from "./compile";
11-
import { handleDependencies } from "./handleDependencies";
1211
import { createContainerFile } from "./createContainerFile";
1312
import { createDeployHash } from "./createDeployHash";
14-
import { readFileSync } from "node:fs";
13+
import { handleDependencies } from "./handleDependencies";
14+
import { Loglevel, LogLevelSchema, PackageManagerSchema } from "./schemas";
15+
import allTestCases from "./testCases.json";
1516

1617
type TestCase = {
1718
name: string;
@@ -24,23 +25,7 @@ type TestCase = {
2425
wantInstallationError?: boolean;
2526
};
2627

27-
const allTestCases: TestCase[] = [
28-
{
29-
name: "no-config",
30-
wantConfigNotFoundError: true,
31-
},
32-
{
33-
name: "server-only",
34-
skipTypecheck: true,
35-
},
36-
{
37-
name: "infisical-sdk",
38-
skipTypecheck: true,
39-
wantCompilationError: true, // FIXME: remove once bug is fixed
40-
},
41-
];
42-
43-
const testCases = process.env.MOD
28+
const testCases: TestCase[] = process.env.MOD
4429
? allTestCases.filter(({ name }) => process.env.MOD === name)
4530
: allTestCases;
4631

‎packages/cli-v3/e2e/testCases.json

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
[
2+
{
3+
"name": "no-config",
4+
"wantConfigNotFoundError": true
5+
},
6+
{
7+
"name": "server-only",
8+
"skipTypecheck": true
9+
}
10+
]

0 commit comments

Comments
 (0)