0
# Vue CLI Plugin E2E Cypress
1

2
Vue CLI plugin that adds End-to-End testing support using Cypress testing framework. It provides a comprehensive testing solution that integrates Cypress into the Vue CLI ecosystem, offering both interactive GUI mode for development and headless mode for CI/CD pipelines.
3

4
## Package Information
5

6
- **Package Name**: @vue/cli-plugin-e2e-cypress
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `vue add e2e-cypress`
10

11
## Core Imports
12

13
This package is a Vue CLI plugin that extends the Vue CLI service with additional commands and functionality. It is not directly imported in application code but instead registers commands and integrates with the Vue CLI system.
14

15
```javascript
16
// Vue CLI plugins are loaded automatically by the CLI service
17
// No direct imports needed in application code
18
```
19

20
## Basic Usage
21

22
```bash
23
# Install the plugin in an existing Vue project
24
vue add e2e-cypress
25

26
# Run e2e tests in interactive mode
27
vue-cli-service test:e2e
28

29
# Run e2e tests in headless mode (for CI)
30
vue-cli-service test:e2e --headless
31

32
# Run tests against a specific URL
33
vue-cli-service test:e2e --url=http://localhost:8080
34

35
# Run a specific test file in headless mode
36
vue-cli-service test:e2e --headless --spec=tests/e2e/specs/test.js
37
```
38

39
## Architecture
40

41
This Vue CLI plugin consists of several key components:
42

43
- **Main Plugin Function**: Registers the `test:e2e` command with the Vue CLI service
44
- **Generator**: Creates initial test structure and configuration files when the plugin is added
45
- **Migrator**: Handles updates and migrations for existing projects
46
- **UI Integration**: Provides Vue CLI UI interface for running tests
47
- **Template System**: Generates Cypress configuration and test files
48

49
## Capabilities
50

51
### Command Registration
52

53
Registers the `test:e2e` command with Vue CLI service for running Cypress tests.
54

55
```javascript { .api }
56
/**
57
 * Main plugin function that registers the test:e2e command
58
 * @param api - Vue CLI Plugin API instance
59
 * @param options - Plugin configuration options
60
 */
61
function plugin(api: PluginAPI, options: PluginOptions): void;
62

63
interface PluginAPI {
64
  registerCommand(name: string, options: CommandOptions, handler: CommandHandler): void;
65
  service: {
66
    run(command: string): Promise<{ url: string; server?: any }>;
67
  };
68
  getCwd(): string;
69
}
70

71
interface CommandOptions {
72
  description: string;
73
  usage: string;
74
  options: Record<string, string>;
75
  details: string;
76
}
77

78
interface CommandHandler {
79
  (args: CommandArgs, rawArgs: string[]): Promise<any>;
80
}
81

82
interface CommandArgs {
83
  headless?: boolean;
84
  mode?: string;
85
  url?: string;
86
  spec?: string;
87
  config?: string | string[];
88
}
89
```
90

91
### Test Execution Command
92

93
The `test:e2e` command that executes Cypress tests with various configuration options.
94

95
**Command**: `vue-cli-service test:e2e [options]`
96

97
**Options:**
98
- `--headless`: Run in headless mode without GUI
99
- `--mode`: Specify the mode the dev server should run in (default: production)
100
- `--url`: Run e2e tests against given URL instead of auto-starting dev server
101
- `-s, --spec`: (headless only) Run a specific spec file, defaults to "all"
102

103
**Usage Examples:**
104

105
```bash
106
# Interactive mode with GUI
107
vue-cli-service test:e2e
108

109
# Headless mode for CI/CD
110
vue-cli-service test:e2e --headless
111

112
# Test against custom URL
113
vue-cli-service test:e2e --url=https://staging.example.com
114

115
# Run specific test file
116
vue-cli-service test:e2e --headless --spec=tests/e2e/specs/login.spec.js
117

118
# Development mode
119
vue-cli-service test:e2e --mode=development
120
```
121

122
### Default Mode Configuration
123

124
Defines the default execution mode for the test:e2e command.
125

126
```javascript { .api }
127
/**
128
 * Default modes configuration for commands
129
 */
130
const defaultModes: {
131
  'test:e2e': string;
132
} = {
133
  'test:e2e': 'production'
134
};
135
```
136

137
### Project Generation
138

139
Generator function that creates the initial Cypress test structure when the plugin is added to a project.
140

141
```javascript { .api }
142
/**
143
 * Generator function that sets up Cypress testing structure
144
 * @param api - Vue CLI Generator API instance
145
 */
146
function generator(api: GeneratorAPI): void;
147

148
interface GeneratorAPI {
149
  render(templatePath: string, data: TemplateData): void;
150
  extendPackage(packageUpdate: PackageUpdate): void;
151
  hasPlugin(pluginName: string): boolean;
152
}
153

154
interface TemplateData {
155
  hasTS: boolean;
156
  hasESLint: boolean;
157
}
158

159
interface PackageUpdate {
160
  devDependencies: Record<string, string>;
161
  scripts: Record<string, string>;
162
}
163
```
164

165
**Generated Structure:**
166
- `cypress.json`: Cypress configuration file
167
- `tests/e2e/plugins/index.js`: Cypress plugins configuration
168
- `tests/e2e/support/index.js`: Cypress support file
169
- `tests/e2e/support/commands.js`: Custom Cypress commands
170
- `tests/e2e/specs/test.js`: Example test specification
171
- `tests/e2e/_eslintrc.js`: ESLint configuration for e2e tests
172

173
### Project Migration
174

175
Migrator function that handles updates to existing projects when the plugin is upgraded.
176

177
```javascript { .api }
178
/**
179
 * Migrator function that handles plugin upgrades and ensures Cypress dependency
180
 * @param api - Vue CLI Migrator API instance
181
 */
182
function migrator(api: MigratorAPI): void;
183

184
interface MigratorAPI {
185
  extendPackage(packageUpdateFn: PackageUpdateFunction): void;
186
}
187

188
interface PackageUpdateFunction {
189
  (pkg: PackageJSON): PackageUpdate | undefined;
190
}
191

192
interface PackageJSON {
193
  dependencies?: Record<string, string>;
194
  devDependencies?: Record<string, string>;
195
  optionalDependencies?: Record<string, string>;
196
}
197
```
198

199
### Vue CLI UI Integration
200

201
UI integration function that provides graphical interface for running tests in Vue CLI UI.
202

203
```javascript { .api }
204
/**
205
 * UI integration function for Vue CLI UI
206
 * @param api - Vue CLI UI API instance
207
 */
208
function uiIntegration(api: UIAPI): void;
209

210
interface UIAPI {
211
  describeTask(taskDescriptor: TaskDescriptor): void;
212
}
213

214
interface TaskDescriptor {
215
  match: RegExp;
216
  description: string;
217
  link: string;
218
  prompts: UIPrompt[];
219
  onBeforeRun: BeforeRunHandler;
220
}
221

222
interface UIPrompt {
223
  name: string;
224
  type: 'confirm' | 'list' | 'input';
225
  default: any;
226
  description: string;
227
  choices?: UIChoice[];
228
}
229

230
interface UIChoice {
231
  name: string;
232
  value: string;
233
}
234

235
interface BeforeRunHandler {
236
  (context: { answers: Record<string, any>; args: string[] }): void;
237
}
238
```
239

240
### Utility Functions
241

242
```javascript { .api }
243
/**
244
 * Removes specified arguments from command line arguments array
245
 * @param rawArgs - Array of command line arguments
246
 * @param argToRemove - Name of argument to remove (without --)
247
 * @param offset - Number of additional arguments to remove (default: 1)
248
 */
249
function removeArg(rawArgs: string[], argToRemove: string, offset?: number): void;
250
```
251

252
## Types
253

254
```javascript { .api }
255
/**
256
 * Plugin configuration options
257
 */
258
interface PluginOptions {
259
  [key: string]: any;
260
}
261

262
/**
263
 * Cypress execution modes
264
 */
265
type CypressMode = 'open' | 'run';
266

267
/**
268
 * Server execution mode
269
 */
270
type ServerMode = 'development' | 'production' | 'test';
271

272
/**
273
 * Test execution result
274
 */
275
interface TestResult {
276
  success: boolean;
277
  exitCode?: number;
278
}
279
```
280

281
## Dependencies
282

283
### Runtime Dependencies
284
- **@vue/cli-shared-utils**: Vue CLI shared utilities for logging, process execution, and module resolution (version ^5.0.9)
285
- **eslint-plugin-cypress**: ESLint plugin providing Cypress-specific rules and globals (version ^2.11.2)
286

287
### Peer Dependencies
288
- **@vue/cli-service**: Vue CLI service (versions 3.x, 4.x, or 5.x)
289
- **cypress**: Cypress testing framework (any version)
290

291
### Generated DevDependencies
292
- **cypress**: Cypress testing framework (version ^9.7.0 by default)
293

294
## Configuration
295

296
The plugin creates a `cypress.json` configuration file with the following default settings:
297

298
```json
299
{
300
  "pluginsFile": "tests/e2e/plugins/index.js"
301
}
302
```
303

304
Additional Cypress configuration options can be added to this file. See the [Cypress Configuration documentation](https://docs.cypress.io/guides/references/configuration.html) for all available options.
305

306
## Environment Variables
307

308
Cypress tests support environment variables through:
309
- `cypress.json`: Global configuration
310
- `cypress.env.json`: Environment-specific variables
311
- Environment variables prefixed with `CYPRESS_`
312

313
Variables are accessible in tests via `Cypress.env('VARIABLE_NAME')`.