Configuration Strategy
This framework uses separate configuration files for UI and API tests, allowing each test type to have optimized settings:
cypress.config.ui.ts
Configuration for UI tests targeting web applications
cypress.config.api.ts
Configuration for API tests targeting REST endpoints
UI Test Configuration
The UI configuration is optimized for browser-based testing:
import { defineConfig } from "cypress";
export default defineConfig({
e2e: {
baseUrl: 'https://www.saucedemo.com/',
specPattern: 'cypress/e2e/ui/**/*.cy.ts',
supportFile: 'cypress/support/e2e.ts',
watchForFileChanges: false,
setupNodeEvents(on, config) {
// implement node event listeners here
},
},
});
UI Configuration Options
The base URL for all cy.visit() commands in UI tests.baseUrl: 'https://www.saucedemo.com/'
cy.visit('/') // → https://www.saucedemo.com/
cy.visit('/cart') // → https://www.saucedemo.com/cart
Use environment variables for different environments:baseUrl: process.env.BASE_URL || 'https://www.saucedemo.com/'
Glob pattern to locate UI test files.specPattern: 'cypress/e2e/ui/**/*.cy.ts'
- Looks in
cypress/e2e/ui/ directory
- Matches all files ending in
.cy.ts
- Includes files in subdirectories (
**)
Example matches:
cypress/e2e/ui/LoginPageSpec.cy.tscypress/e2e/ui/checkout/payment.cy.ts
Controls whether Cypress auto-reloads tests when files change.watchForFileChanges: false
false: Tests don’t auto-reload (recommended for stability)true: Tests reload on file changes (can be distracting)
Setting this to false prevents unexpected test reruns during development, giving you more control.
Path to the file that loads before all tests.supportFile: 'cypress/support/e2e.ts'
- Custom commands
- Global hooks
- Third-party plugins
API Test Configuration
The API configuration targets REST endpoints:
import { defineConfig } from "cypress";
export default defineConfig({
e2e: {
baseUrl: 'https://restful-booker.herokuapp.com',
specPattern: 'cypress/e2e/api/**/*.cy.ts',
supportFile: 'cypress/support/e2e.ts',
watchForFileChanges: false,
setupNodeEvents(on, config) {
// implement node event listeners here
},
},
});
API Configuration Differences
Different baseUrl
Points to the API endpoint instead of a web application:baseUrl: 'https://restful-booker.herokuapp.com'
cy.request('/booking') // → https://restful-booker.herokuapp.com/booking
cy.request('/auth') // → https://restful-booker.herokuapp.com/auth
Different specPattern
Only runs tests in the api/ directory:specPattern: 'cypress/e2e/api/**/*.cy.ts'
Same supportFile
Both configurations share the same support file, allowing shared commands and setup.
Running with Different Configurations
Use the --config-file flag to specify which configuration to use:
npx cypress open --config-file cypress.config.ui.ts
# OR use the npm script
npm run cy:open:ui
Additional Configuration Options
You can extend configurations with additional Cypress options:
Viewport Settings (UI Tests)
export default defineConfig({
e2e: {
baseUrl: 'https://www.saucedemo.com/',
specPattern: 'cypress/e2e/ui/**/*.cy.ts',
viewportWidth: 1280,
viewportHeight: 720,
// ...
},
});
Timeout Settings
export default defineConfig({
e2e: {
baseUrl: 'https://www.saucedemo.com/',
defaultCommandTimeout: 10000, // 10 seconds
requestTimeout: 15000, // 15 seconds for API calls
responseTimeout: 15000, // 15 seconds for responses
pageLoadTimeout: 30000, // 30 seconds for page loads
// ...
},
});
Video and Screenshot Settings
export default defineConfig({
e2e: {
baseUrl: 'https://www.saucedemo.com/',
video: true, // Record videos of test runs
screenshotOnRunFailure: true, // Take screenshots on failure
videosFolder: 'cypress/videos',
screenshotsFolder: 'cypress/screenshots',
// ...
},
});
Browser Launch Options
export default defineConfig({
e2e: {
baseUrl: 'https://www.saucedemo.com/',
setupNodeEvents(on, config) {
on('before:browser:launch', (browser, launchOptions) => {
if (browser.name === 'chrome') {
launchOptions.args.push('--disable-dev-shm-usage')
}
return launchOptions
})
},
},
});
Environment Variables
Use environment variables for dynamic configuration:
export default defineConfig({
e2e: {
baseUrl: process.env.CYPRESS_BASE_URL || 'https://www.saucedemo.com/',
env: {
apiUrl: 'https://restful-booker.herokuapp.com',
username: process.env.TEST_USERNAME,
password: process.env.TEST_PASSWORD,
},
},
});
const apiUrl = Cypress.env('apiUrl')
const username = Cypress.env('username')
CYPRESS_BASE_URL=https://staging.example.com npm run cy:run:ui
Configuration Inheritance
You can create a base configuration and extend it:
import { defineConfig } from "cypress";
export const baseConfig = defineConfig({
e2e: {
supportFile: 'cypress/support/e2e.ts',
watchForFileChanges: false,
video: true,
screenshotOnRunFailure: true,
},
});
import { baseConfig } from './cypress.config.base'
export default {
...baseConfig,
e2e: {
...baseConfig.e2e,
baseUrl: 'https://www.saucedemo.com/',
specPattern: 'cypress/e2e/ui/**/*.cy.ts',
},
}
Configuration inheritance reduces duplication and ensures consistent settings across test types.
setupNodeEvents
The setupNodeEvents function allows you to tap into Node.js events:
setupNodeEvents(on, config) {
// Task registration
on('task', {
log(message) {
console.log(message)
return null
},
})
// File preprocessing
on('file:preprocessor', (file) => {
// Custom file processing
})
// Before browser launch
on('before:browser:launch', (browser, launchOptions) => {
// Modify browser launch options
return launchOptions
})
return config
}
- Database seeding
- File system operations
- Custom reporting
- Environment-specific setup
Configuration Best Practices
Separate Concerns
Keep UI and API configurations separate for clarity and optimization
Use Environment Variables
Never hardcode sensitive data or environment-specific values
Document Custom Settings
Add comments explaining non-obvious configuration choices
Share Common Settings
Use configuration inheritance for shared options
Troubleshooting
Check that specPattern matches your test file locations:# List files that match the pattern
ls cypress/e2e/ui/**/*.cy.ts
Ensure you’re using the correct config file:# For UI tests
npm run cy:open:ui
# NOT
npm run cy:open:api
Verify the supportFile path is correct:supportFile: 'cypress/support/e2e.ts' // Should match actual file
Next Steps
Writing UI Tests
Apply UI configuration in your tests
Writing API Tests
Use API configuration for endpoint testing
Running Tests
Execute tests with different configurations
Maintainability
Keep configurations clean and maintainable
