GraphQL API

相关源文件

• packages/app/cypress/e2e/specs.cy.ts
• packages/data-context/__snapshots__/data-context.spec.ts.js
• packages/data-context/src/DataContext.ts
• packages/data-context/src/actions/DataEmitterActions.ts
• packages/data-context/src/actions/ElectronActions.ts
• packages/data-context/src/actions/ProjectActions.ts
• packages/data-context/src/actions/WizardActions.ts
• packages/data-context/src/data/CypressEnv.ts
• packages/data-context/src/data/ProjectConfigIpc.ts
• packages/data-context/src/data/ProjectConfigManager.ts
• packages/data-context/src/data/ProjectLifecycleManager.ts
• packages/data-context/src/data/coreDataShape.ts
• packages/data-context/src/index.ts
• packages/data-context/src/sources/ProjectDataSource.ts
• packages/data-context/src/util/pluginHandlers.ts
• packages/data-context/test/unit/data/ProjectConfigIpc.spec.ts
• packages/data-context/test/unit/helper.ts
• packages/data-context/test/unit/sources/ProjectDataSource.spec.ts
• packages/frontend-shared/cypress/support/e2e.ts
• packages/frontend-shared/cypress/support/mock-graphql/stubgql-Mutation.ts
• packages/frontend-shared/cypress/support/mock-graphql/stubgql-Query.ts
• packages/frontend-shared/src/locales/en-US.json
• packages/graphql/schemas/schema.graphql
• packages/graphql/src/makeGraphQLServer.ts
• packages/graphql/src/schemaTypes/objectTypes/gql-Mutation.ts
• packages/graphql/src/schemaTypes/objectTypes/gql-ProjectPreferences.ts
• packages/graphql/src/schemaTypes/objectTypes/gql-Query.ts
• packages/graphql/src/schemaTypes/objectTypes/gql-Subscription.ts
• packages/graphql/src/schemaTypes/objectTypes/index.ts
• packages/launchpad/cypress/e2e/project-setup.cy.ts
• packages/launchpad/cypress/e2e/scaffold-project.cy.ts
• packages/launchpad/cypress/e2e/slow-network.cy.ts
• packages/launchpad/cypress/tasks/snapshotsScaffold.ts
• packages/launchpad/src/Main.vue
• packages/launchpad/src/migration/MajorVersionWelcome.cy.tsx
• packages/launchpad/src/migration/MajorVersionWelcome.vue
• packages/server/lib/makeDataContext.ts
• packages/server/lib/modes/run.ts
• packages/server/lib/open_project.ts
• packages/types/src/constants.ts
• packages/types/src/index.ts
• packages/types/src/server.ts
• packages/types/src/spec.ts
• system-tests/projects/no-server/cypress.config.js
• system-tests/projects/pristine/expected-cypress-js-e2e-without-fixtures/cypress/support/commands.js
• system-tests/projects/pristine/expected-cypress-js-e2e-without-fixtures/cypress/support/e2e.js
• system-tests/test-binary/ci_environments_spec.ts
• system-tests/test-binary/node_versions_spec.ts

GraphQL API 是 Cypress 用户界面组件（App 和 Launchpad）与核心测试基础设施之间的中心通信层。它提供了一种类型安全、结构化的方式来查询和操作与项目、测试配置、浏览器和云集成相关的数据。

目的与范围

此页面介绍了为 Cypress 的 Launchpad 和 App 界面提供支持的内部 GraphQL API 架构。此 API 不同于测试文件中使用的 Cypress 测试 API（有关测试 API 的信息，请参阅命令执行）。

GraphQL API 支持

1. 查询项目状态、配置和可用浏览器
2. 管理项目生命周期（创建、打开、配置项目）
3. 执行诸如运行测试和生成 spec 文件之类的操作
4. 同步 UI 和测试基础设施之间的状态
5. 促进 Cypress Cloud 集成以记录运行和分析

来源：packages/graphql/src/schemaTypes/objectTypes/gql-Mutation.ts packages/data-context/src/DataContext.ts

GraphQL Schema 架构

GraphQL schema 定义了 API 的类型系统和可用的操作。它包含项目、浏览器、specs、云数据等的类型。

来源：packages/graphql/schemas/schema.graphql5-200 packages/graphql/schemas/schema.graphql200-500

DataContext 作为中心枢纽

DataContext 类是所有数据操作的中心枢纽，也是 GraphQL 查询和突变的解析器上下文。

来源：packages/data-context/src/DataContext.ts83-290 packages/data-context/src/data/coreDataShape.ts136-180

GraphQL 请求-响应流

以下图表说明了 GraphQL 请求如何流经系统

来源：packages/data-context/src/actions/DataEmitterActions.ts packages/server/lib/makeDataContext.ts40-100

关键 GraphQL 类型

与项目相关的类型

来源：packages/graphql/schemas/schema.graphql5-40 packages/graphql/schemas/schema.graphql963-1066

浏览器类型

来源：packages/graphql/schemas/schema.graphql24-40 packages/graphql/schemas/schema.graphql42-52

关键 GraphQL Mutations

GraphQL API 提供了许多用于在 Cypress 中执行操作的 mutations。以下是按功能组织的最重要的 mutations：

项目管理 Mutations

Mutation	描述
setCurrentProject	打开指定路径的项目
addProject	将项目添加到最近的项目列表
clearCurrentProject	关闭当前项目
launchProject	在浏览器中启动项目
setProjectPreferencesInGlobalCache	保存项目偏好设置

测试执行 Mutations

Mutation	描述
runSpec	运行指定的测试 spec 文件
setAndLoadCurrentTestingType	设置测试类型（E2E 或 Component）
generateSpecFromSource	从源代码生成 spec 文件
scaffoldTestingType	为项目配置测试类型

浏览器管理 Mutations

Mutation	描述
launchpadSetBrowser	设置活动浏览器
focusActiveBrowserWindow	聚焦活动浏览器窗口

Cloud 集成 Mutations

Mutation	描述
login	登录 Cypress Cloud
logout	退出 Cypress Cloud
resetAuthState	重置认证状态

来源：packages/graphql/src/schemaTypes/objectTypes/gql-Mutation.ts packages/graphql/src/schemaTypes/objectTypes/gql-Mutation.ts359-425

项目生命周期管理

The ProjectLifecycleManager 类是 GraphQL API 操作的核心，因为它管理着完整的项目生命周期。

来源：packages/data-context/src/data/ProjectLifecycleManager.ts packages/data-context/src/actions/ProjectActions.ts91-305

配置加载过程

GraphQL API 通过一个复杂的过程管理项目配置的加载

来源：packages/data-context/src/data/ProjectConfigManager.ts packages/data-context/src/data/ProjectConfigIpc.ts1-40

浏览器启动流程

浏览器启动过程是 GraphQL API 功能的关键部分

来源：packages/data-context/src/actions/ProjectActions.ts packages/server/lib/open_project.ts58-98

实际示例

示例 1：打开项目

当用户在 Launchpad 中打开一个项目时

1. UI 会使用项目路径触发 setCurrentProject mutation
2. GraphQL 将其解析为 ProjectActions.setCurrentProject()
3. ProjectLifecycleManager 初始化项目
4. ProjectConfigManager 加载并验证配置
5. 检测测试类型并准备配置
6. Launchpad UI 更新以显示项目仪表板

示例 2：运行 Spec

当用户运行一个 spec 时

1. UI 会使用 spec 路径触发 launchProject mutation
2. GraphQL 将其解析为 ProjectActions.launchProject()
3. 确定活动浏览器
4. 验证 spec 路径
5. 调用 openProject.launch() 并传入浏览器和 spec
6. 使用适当的配置启动浏览器
7. 加载 spec 并执行测试

错误处理

GraphQL API 通过 ErrorWrapper 类型包含强大的错误处理机制

来源： packages/graphql/schemas/schema.graphql1268-1297 packages/graphql/schemas/schema.graphql1111-1267

结论

GraphQL API 是 Cypress 交互式 UI 的基础，它在用户界面组件和底层测试基础设施之间提供了强大、类型安全的接口。它在保持关注点清晰分离的同时，实现了 Cypress App 和 Launchpad 的丰富、响应式体验。

通过其明确定义的模式、解析器架构以及与 DataContext 的集成，GraphQL API 能够实现项目配置、测试执行和云集成等复杂操作，同时提供清晰的错误处理和状态管理。

来源： packages/data-context/src/data/ProjectLifecycleManager.ts packages/graphql/src/schemaTypes/objectTypes/gql-Mutation.ts packages/data-context/src/DataContext.ts