前端Cypress配置规范书

前端Cypress配置规范书一、Cypress基础配置规范1.1项目结构标准化Cypress项目应遵循统一的目录结构，确保团队成员能够快速定位各类文件。基础结构如下：cypress/├──fixtures/#测试数据文件│├──api/#接口测试数据│└──ui/#UI测试数据├──e2e/#端到端测试用例│├──modules/#按业务模块划分测试用例││├──user/#用户模块测试││└──order/#订单模块测试│└──common/#通用场景测试├──support/#全局支持文件│├──commands.js#自定义命令│├──e2e.js#全局测试钩子│└──utils/#工具函数库└──downloads/#测试下载文件存储目录fixtures目录：按测试类型（API/UI）进一步细分，数据文件采用JSON格式命名，如user_login_success.json，便于识别用途。e2e目录：以业务模块为核心划分测试用例，每个模块下的测试文件命名需包含功能描述，如user_login_spec.js。support目录：集中管理全局配置与工具函数，避免测试用例中出现重复代码。1.2核心配置文件规范cypress.config.js作为Cypress的核心配置文件，需遵循以下规范：const{defineConfig}=require('cypress');module.exports=defineConfig({e2e:{baseUrl:'',//统一测试域名specPattern:'cypress/e2e/**/*.spec.{js,jsx,ts,tsx}',//测试文件匹配规则supportFile:'cypress/support/e2e.js',//全局支持文件路径fixturesFolder:'cypress/fixtures',//测试数据目录downloadsFolder:'cypress/downloads',//下载文件存储目录video:false,//默认禁用测试录屏（按需开启）screenshotOnRunFailure:true,//测试失败时自动截图pageLoadTimeout:60000,//页面加载超时时间（毫秒）defaultCommandTimeout:10000,//命令默认超时时间（毫秒）requestTimeout:15000,//接口请求超时时间（毫秒）responseTimeout:30000,//接口响应超时时间（毫秒）env:{//全局环境变量TEST_USER:'test_user@',TEST_PASSWORD:'test_password'},setupNodeEvents(on,config){//自定义Node事件处理require('cypress-mochawesome-reporter/plugin')(on);//集成测试报告插件}},viewportWidth:1920,//默认测试窗口宽度viewportHeight:1080,//默认测试窗口高度retries:{runMode:2,//运行模式下失败重试次数openMode:0//调试模式下禁用重试}});baseUrl配置：统一设置测试域名，避免在测试用例中硬编码URL。超时时间配置：根据项目实际情况合理设置各类超时时间，平衡测试稳定性与执行效率。环境变量管理：敏感信息（如测试账号密码）应通过环境变量注入，避免硬编码在配置文件中。重试机制：运行模式下启用失败重试，减少偶发性失败对测试结果的影响。二、测试用例编写规范2.1用例结构与命名规范每个测试用例文件需遵循describe-it结构，且命名清晰明确：describe('用户模块-登录功能',()=>{beforeEach(()=>{cy.visit('/login');//前置操作：访问登录页面});it('输入正确账号密码，成功登录系统',()=>{cy.get('#username').type('test_user');cy.get('#password').type('test_password');cy.get('#login-btn').click();cy.url().should('include','/dashboard');//断言：跳转至首页});it('输入错误密码，显示登录失败提示',()=>{cy.get('#username').type('test_user');cy.get('#password').type('wrong_password');cy.get('#login-btn').click();cy.get('.error-message').should('contain','账号或密码错误');//断言：错误提示显示});});describe块命名：采用“模块名称-功能名称”格式，清晰标识测试范围。it块命名：以行为驱动的方式描述测试场景，如“输入正确账号密码，成功登录系统”，便于理解测试意图。前置操作：通过beforeEach/before钩子提取重复的前置步骤，保持测试用例简洁。2.2元素定位规范元素定位是UI测试的核心，需遵循稳定性与可读性原则：优先使用data属性定位<buttondata-testid="login-submit-btn">登录</button>cy.get('[data-testid="login-submit-btn"]').click();为测试元素添加data-testid属性，避免因CSS类名或文本内容变化导致测试失败。避免使用不稳定定位方式禁止使用cy.get('.btn-primary')这类依赖CSS类名的定位方式，类名可能因样式调整而变更。谨慎使用cy.contains('登录')，当页面存在多个相同文本元素时，可能导致定位错误。复杂场景定位策略对于动态生成的元素，结合元素层级与属性组合定位：cy.get('.user-list').find('[data-testid="user-item"]').eq(0).click();先定位父容器，再通过索引或子元素属性定位目标元素，提高定位稳定性。2.3断言规范断言需精准、明确，避免模糊判断：优先使用Cypress内置断言cy.url().should('include','/dashboard');//断言URL包含指定路径cy.get('.user-name').should('have.text','测试用户');//断言元素文本内容cy.get('#email-input').should('be.enabled');//断言元素可用状态Cypress提供了丰富的内置断言方法，覆盖常见的测试场景，无需额外引入断言库。避免使用等待断言禁止使用cy.wait(5000)这类固定等待时间的方式，应使用基于条件的等待：//错误示例cy.wait(5000);cy.get('.loading').should('not.exist');//正确示例cy.get('.loading',{timeout:10000}).should('not.exist');通过设置超时时间，让Cypress自动等待条件满足，提高测试稳定性。多条件断言组合对于复杂场景，使用and组合多个断言：cy.get('#user-profile').should('be.visible').and('have.attr','data-testid','user-profile-card').and('contain','测试用户');一次性验证元素的可见性、属性与文本内容，减少断言代码的冗余。三、自定义命令与工具函数规范3.1自定义命令规范自定义命令用于封装重复的操作流程，需遵循以下规范：//cypress/support/commands.jsCypress.Commands.add('login',(username,password)=>{cy.visit('/login');cy.get('[data-testid="username-input"]').type(username);cy.get('[data-testid="password-input"]').type(password);cy.get('[data-testid="login-submit-btn"]').click();cy.url().should('include','/dashboard');//内置断言确保登录成功});命令命名：采用动词开头的驼峰式命名，如login、addCartItem，清晰表达命令功能。参数设计：必要时接收参数，提高命令的通用性，如支持不同账号登录。内置断言：在命令内部添加必要的断言，确保命令执行成功后进入预期状态。3.2工具函数规范通用工具函数应集中在support/utils目录下，按功能模块划分：//cypress/support/utils/dateUtils.jsexportconstformatDate=(date,format='YYYY-MM-DD')=>{//日期格式化逻辑};exportconstgetTomorrowDate=()=>{//获取明天日期逻辑};函数命名：采用动词+名词的格式，如formatDate、generateRandomString，明确函数用途。单一职责：每个工具函数仅负责一项功能，避免出现“万能函数”。类型定义：使用TypeScript编写工具函数时，需添加完整的类型注解，提高代码可读性。四、API测试配置规范4.1API测试结构规范API测试用例应与UI测试分离，单独存放在e2e/api目录下，结构如下：cypress/e2e/api/├──user/#用户接口测试│├──login_spec.js#登录接口测试│└──profile_spec.js#用户信息接口测试└──order/#订单接口测试├──list_spec.js#订单列表接口测试└──detail_spec.js#订单详情接口测试文件命名：采用“接口功能_spec.js”格式，如user_login_spec.js，便于识别测试的接口。4.2API请求规范API测试需遵循统一的请求格式，确保测试用例的一致性：describe('用户接口-登录接口',()=>{it('POST/api/user/login-正确账号密码登录成功',()=>{cy.request({method:'POST',url:'/api/user/login',body:{username:'test_user',password:'test_password'}}).then((response)=>{expect(response.status).to.eq(200);//断言响应状态码expect(response.body.code).to.eq(0);//断言业务状态码expect(response.body.data).perty('token');//断言返回数据结构});});it('POST/api/user/login-错误密码登录失败',()=>{cy.request({method:'POST',url:'/api/user/login',failOnStatusCode:false,//禁用默认的失败状态码断言body:{username:'test_user',password:'wrong_password'}}).then((response)=>{expect(response.status).to.eq(200);//断言响应状态码expect(response.body.code).to.eq(1001);//断言业务错误码expect(response.body.message).to.eq('账号或密码错误');//断言错误提示信息});});});请求格式：使用cy.request的完整配置格式，明确指定method、url与body参数。状态码处理：对于预期失败的请求，需设置failOnStatusCode:false，避免测试用例直接失败。断言内容：同时断言HTTP状态码、业务状态码与返回数据结构，确保接口完全符合预期。4.3测试数据管理API测试数据应存放在fixtures/api目录下，按接口模块划分：//cypress/fixtures/api/user/login_success.json{"username":"test_user","password":"test_password","expected_token":"mock_token_123456"}数据复用：通过cy.fixture加载测试数据，避免在测试用例中硬编码数据：cy.fixture('api/user/login_success.json').then((data)=>{cy.request({method:'POST',url:'/api/user/login',body:{username:data.username,password:data.password}});});五、测试报告与CI集成规范5.1测试报告配置集成Mochawesome测试报告，提升测试结果的可读性：安装依赖npminstallcypress-mochawesome-reporter--save-dev配置报告插件在cypress.config.js中添加插件配置：setupNodeEvents(on,config){require('cypress-mochawesome-reporter/plugin')(on);}在support/e2e.js中导入报告样式：import'cypress-mochawesome-reporter/register';报告生成运行测试后，报告将自动生成在cypress/reports目录下，包含HTML格式的可视化报告与JSON格式的原始数据。5.2CI/CD集成规范Cypress测试需与CI/CD流程深度集成，实现自动化测试：GitHubActions配置示例name:CypressE2ETestson:[push,pull_request]jobs:cypress-run:runs-on:ubuntu-lateststeps:-name:Checkoutcodeuses:actions/checkout@v4-name:SetupNode.jsuses:actions/setup-node@v4with:node-version:'20'-name:Installdependenciesrun:npmci-name:RunCypresstestsuses:cypress-io/github-action@v6with:command:npmruntest:e2erecord:true#开启测试结果录制（需配置CypressDashboard）env:CYPRESS_RECORD_KEY:${{secrets.CYPRESS_RECORD_KEY}}TEST_USER:${{secrets.TEST_USER}}TEST_PASSWORD:${{secrets.TEST_PASSWORD}}环境变量管理：敏感信息（如测试账号、Cypress录制密钥）通过GitHubSecrets注入，避免硬编码在配置文件中。测试录制：开启CypressDashboard录制功能，便于跟踪测试历史与失败用例。六、性能与稳定性优化规范6.1测试执行速度优化并行测试配置在cypress.config.js中启用并行测试：module.exports=defineConfig({e2e:{//其他配置numTestsKeptInMemory:0,//禁用测试用例内存缓存},parallel:true,//启用并行测试//其他配置});结合CI/CD环境的并发能力，合理设置并行测试数量，提高测试执行效率。禁用不必要的功能在运行模式下禁用录屏与截图功能，减少资源消耗：module.exports=defineConfig({e2e:{video:false,//禁用录屏screenshotOnRunFailure:false,//禁用失败截图}});6.2测试稳定性优化避免测试用例依赖每个测试用例应独立执行，避免依赖其他用例的执行结果：//错误示例：依赖前一个用例创建的用户it('测试用户订单列表',()=>{cy.get('.order-list').should('have.length.greaterThan',0);});//正确示例：每个用例独立准备测试数据it('测试用户订单列表',()=>{cy.createTestUser();//独立创建测试用户cy.login('test_user','test_password');cy.get('.order-list').should('have.length.greaterThan',0);});智能等待策略充分利用Cypress的自动等待机制，避免使用固定等待时间：//错误示例cy.wait(3000);cy.get('.loading').should('not.exist');//正确示例cy.get('.loading',{timeout:10000}).should('not.exist');通过设置超时时间，让Cypress自动等待元素状态变化，提高测试稳定性。七、代码质量与协作规范7.1ESLint