|
1 | 1 | # @packages/electron |
2 | 2 |
|
3 | | -This is the lib responsible for installing + building Electron. This enables us to develop with the Electron shell that will match how the final compiled Cypress binary looks 1:1. |
| 3 | +This package is responsible for installing, building, and managing the Electron binary that powers Cypress. It enables development with an Electron shell that matches the final compiled Cypress binary 1:1 by using symlinks during development. |
4 | 4 |
|
5 | | -It does this by using symlinks while in development. |
| 5 | +## Build System |
| 6 | + |
| 7 | +The package uses TypeScript to compile to CJS. ESM builds are not run by default, but can be enabled or tested with `build:esm`. |
| 8 | +- **CommonJS**: Primary build used by the binary script and other packages |
| 9 | +- **ES Modules**: Alternative build for modern Node.js applications |
| 10 | +- **Output**: Compiled JavaScript in `dist/cjs/`, and a binary in `dist/Cypress`. |
6 | 11 |
|
7 | 12 | ## Building |
8 | 13 |
|
9 | 14 | ```bash |
| 15 | +# Build both CommonJS and ES Module versions |
10 | 16 | yarn workspace @packages/electron build |
| 17 | + |
| 18 | +# Build only CommonJS version |
| 19 | +yarn workspace @packages/electron build:cjs |
| 20 | + |
| 21 | +# Build only ES Module version |
| 22 | +yarn workspace @packages/electron build:esm |
| 23 | + |
| 24 | +# Clean build artifacts |
| 25 | +yarn workspace @packages/electron clean-deps |
| 26 | +``` |
| 27 | + |
| 28 | +**Note**: The build process compiles TypeScript source to JavaScript. The `--install` command packages the actual Electron binary for your OS-specific platform. |
| 29 | + |
| 30 | +## Usage |
| 31 | + |
| 32 | +### Command Line Interface |
| 33 | + |
| 34 | +The package provides a binary script `cypress-electron` with several commands: |
| 35 | + |
| 36 | +```bash |
| 37 | +# Install/build Electron binary for current platform |
| 38 | +./bin/cypress-electron --install |
| 39 | + |
| 40 | +# Show help and usage information |
| 41 | +./bin/cypress-electron --help |
| 42 | + |
| 43 | +# Launch an Electron app (development mode) |
| 44 | +./bin/cypress-electron /path/to/your/app |
| 45 | + |
| 46 | +# Launch with debugging enabled |
| 47 | +./bin/cypress-electron /path/to/your/app --inspect-brk |
| 48 | +``` |
| 49 | + |
| 50 | +These commands are parsed out from argv in the `cli()` function defined in `./lib/electron.ts` |
| 51 | + |
| 52 | +### Public Interface |
| 53 | + |
| 54 | +```typescript |
| 55 | +/** |
| 56 | + * Checks if Electron binary exists and is up-to-date, installs if needed |
| 57 | + */ |
| 58 | +function installIfNeeded(): Promise<void> |
| 59 | + |
| 60 | +/** |
| 61 | + * Forces installation of Electron binary with optional arguments |
| 62 | + */ |
| 63 | +function install(...args: any[]): Promise<void> |
| 64 | + |
| 65 | +/** |
| 66 | + * Launches an Electron app with the specified path and arguments |
| 67 | + * @param appPath - Path to the application to launch |
| 68 | + * @param argv - Command line arguments to pass to the app |
| 69 | + * @param callback - Optional callback when the app exits |
| 70 | + * @returns Promise that resolves to the spawned Electron process |
| 71 | + */ |
| 72 | +function open( |
| 73 | + appPath: string, |
| 74 | + argv: string[], |
| 75 | + callback?: (code: number) => void |
| 76 | +): Promise<ChildProcess> |
| 77 | + |
| 78 | +/** |
| 79 | + * Returns the Electron version being used |
| 80 | + * @returns String version (e.g., "36.4.0") |
| 81 | + */ |
| 82 | +function getElectronVersion(): string |
| 83 | + |
| 84 | +/** |
| 85 | + * Returns the Node.js version bundled with Electron |
| 86 | + * @returns Promise that resolves to Node.js version string |
| 87 | + */ |
| 88 | +function getElectronNodeVersion(): Promise<string> |
| 89 | + |
| 90 | +/** |
| 91 | + * Returns the icons package for platform-specific icon paths |
| 92 | + * @returns Icons package object |
| 93 | + */ |
| 94 | +function icons(): any |
| 95 | + |
| 96 | +/** |
| 97 | + * CLI entry point for command-line operations |
| 98 | + * @param argv - Command line arguments array |
| 99 | + */ |
| 100 | +function cli(argv: string[]): void |
11 | 101 | ``` |
12 | 102 |
|
13 | | -Note: this just installs Electron binary for your OS specific platform |
14 | 103 |
|
15 | 104 | ## Testing |
16 | 105 |
|
17 | 106 | ```bash |
| 107 | +# Run unit tests |
18 | 108 | yarn workspace @packages/electron test |
| 109 | +
|
| 110 | +# Run tests with debugger |
19 | 111 | yarn workspace @packages/electron test-debug |
| 112 | +
|
| 113 | +# Run tests in watch mode |
20 | 114 | yarn workspace @packages/electron test-watch |
21 | 115 | ``` |
22 | 116 |
|
| 117 | +## Package Structure |
| 118 | + |
| 119 | +``` |
| 120 | +packages/electron/ |
| 121 | +├── bin/ # Binary scripts |
| 122 | +│ └── cypress-electron # Main CLI script |
| 123 | +├── lib/ # TypeScript source |
| 124 | +│ ├── electron.ts # Main entry point and CLI logic |
| 125 | +│ ├── install.ts # Installation and packaging logic |
| 126 | +│ ├── paths.ts # Platform-specific path resolution |
| 127 | +│ └── print-node-version.ts |
| 128 | +├── dist/ # Compiled output |
| 129 | +│ ├── cjs/ # CommonJS build |
| 130 | +│ ├── esm/ # ES Module build |
| 131 | +│ └── Cypress/ # Electron app binary (created by --install) |
| 132 | +├── app/ # App template for packaging |
| 133 | +└── test/ # Test files |
| 134 | +``` |
| 135 | +
|
23 | 136 | ## Upgrading Electron |
24 | 137 |
|
25 | 138 | The version of `electron` that is bundled with Cypress should be kept as up-to-date as possible with the [stable Electron releases](https://www.electronjs.org/releases/stable). Many users expect the bundled Chromium and Node.js to be relatively recent. Also, historically, it has been extremely difficult to upgrade over multiple major versions of Electron at once, because of all the breaking changes in Electron and Node.js that impact Cypress. |
@@ -73,6 +186,51 @@ Upgrading `electron` involves more than just bumping this package's `package.jso |
73 | 186 |
|
74 | 187 | - [ ] If needed, update the **[V8 Snapshot Cache](https://github.com/cypress-io/cypress/actions/workflows/update_v8_snapshot_cache.yml)** by running the GitHub workflow. Make sure to use the branch that contains the electron updates to populate the `'workflow from'` and `'branch to update'` arguments. Select `'Generate from scratch'` and `'commit directly to branch'`. This will usually take 6-8 hours to complete and is best to not be actively developing on the branch when this workflow runs. |
75 | 188 |
|
| 189 | +## Development |
| 190 | +
|
| 191 | +### Local Development |
| 192 | +
|
| 193 | +1. **Build the package**: `yarn build:cjs` (or `yarn build` for both formats) |
| 194 | +2. **Test the binary**: `./bin/cypress-electron --install` |
| 195 | +3. **Run tests**: `yarn test` |
| 196 | +
|
| 197 | +### Debugging |
| 198 | +
|
| 199 | +Enable debug logging by setting the `DEBUG` environment variable: |
| 200 | +
|
| 201 | +```bash |
| 202 | +DEBUG=cypress:electron* ./bin/cypress-electron --install |
| 203 | +DEBUG=cypress:electron:install* ./bin/cypress-electron --install |
| 204 | +``` |
| 205 | + |
| 206 | +### Common Issues |
| 207 | + |
| 208 | +#### Build Errors |
| 209 | +- **TypeScript compilation errors**: Check that all dependencies are installed and TypeScript config is correct |
| 210 | +- **Missing dependencies**: Ensure `@electron/packager` and other dev dependencies are available |
| 211 | + |
| 212 | +#### Runtime Errors |
| 213 | +- **Path resolution issues**: Verify that the compiled output structure matches the expected paths |
| 214 | +- **Binary not found**: Run `./bin/cypress-electron --install` to create the Electron binary |
| 215 | +- **Permission errors**: On Linux, ensure proper permissions for the binary directory |
| 216 | + |
| 217 | +#### Platform-Specific Issues |
| 218 | +- **macOS**: ARM64 vs x64 architecture detection may need updates |
| 219 | +- **Linux**: Sandbox issues when running as root (automatically handled) |
| 220 | +- **Windows**: Junction vs directory symlink handling (automatically handled) |
| 221 | + |
| 222 | +## Contributing |
| 223 | + |
| 224 | +When contributing to this package: |
| 225 | + |
| 226 | +1. **Follow the existing patterns** for error handling and logging |
| 227 | +2. **Test on multiple platforms** if making platform-specific changes |
| 228 | +3. **Update tests** for any new functionality |
| 229 | +4. **Rebuild after changes** using `yarn build:cjs` |
| 230 | +5. **Test the binary** with `./bin/cypress-electron --install` |
| 231 | + |
| 232 | +For more detailed information about the build system, see [BUILD.md](./BUILD.md). |
| 233 | + |
76 | 234 |
|
77 | 235 | ### Common Upgrade Issues |
78 | 236 |
|
|
0 commit comments