跳转到内容

本页由英文自动翻译。

阅读英文版

注册表单规格逐屏说明你的表单要填什么:每个字段在字段目录中的分区、标签、是否必填以及测试 ID。可以在应用中创建,也可以让编程智能体根据你的描述或表单截图创建,然后保存到项目。保存时会使用已经能填写其字段的自定义字段,并为没有对应字段的地方创建所需的自定义字段,这样 form_values 会填写所有能安全填写的字段,其余留给你的测试。

一个项目最多保存 20 个注册表单。

让你的智能体运行 build_signup_form_from_screenshot 提示词,然后分享表单每个页面的截图。它会读取字段,以表格形式展示规格供你修改,只有在你确认后才保存。

截图只留在你的智能体那里:只有你确认的规格会发送到 Proxy Mail QA。

你也可以直接描述表单:“邮箱、密码、公司规模和条款勾选框,然后第二个页面填写你的职位”。

打开 Project settings → Forms 并选择 New form。从模板或空白表单开始,然后:

  • 从目录中为每个页面添加字段,修改标签,并设置是否必填
  • 在字段的选项按钮下设置选项:密码长度和必须包含的字符、最小年龄、国家,或下拉菜单的选项
  • 添加页面,每个页面有自己的标题和页面路径
  • 在 Preview 查看效果,在 Code 查看代码,在 Test 查看测试,每处都有 Copy

留空的标签会使用表单的语言。每个字段都会说明它由谁填写:Proxy Mail QA、现成的自定义字段,或你的测试。表单保存后,由自定义字段填写的字段会显示其名称,并提供 Open 跳转到 Project settings → Custom fields 中查看,自定义字段关闭时也会注明。被你的某个 标准字段 设置关闭的字段会注明这一点,并提供跳转按钮。电话、证件号或税号字段、选项或条款勾选框由 现成字段 填写:表单创建的那个、按测试 ID 匹配的那个,或项目中该类字段自己的那个。电话字段会注明何时由你的测试输入:项目的 Phone number 会填入英国、澳大利亚、美国和加拿大专门留作虚构用途的号码,其他国家则填入你应用的测试号码,两者都没有的国家则留空。

在 Custom fields 中,表单创建的每个自定义字段都有一个带表单名称的 From 标签,点击可打开该表单。你自己创建、被表单直接使用的字段有 Used by 标签。

表单描述你的注册页面:页面、字段、标签和测试 ID,用于生成代码、测试和预览。自定义字段决定每次填写时字段里填什么,不管有没有表单。表单永远不需要为同一个字段再建一个自定义字段:

  • 使用已有的。 如果你的某个自定义字段已经能填写某个字段,例如项目现成的 Phone number,或你为公司规模问题设置的规则,保存时会使用它。只有在没有字段能填写时,才会创建现成字段。
  • 不会悄悄覆盖你的。 如果表单创建的现成字段优先于你自己的自定义字段(比如你在保存表单后添加了自己的规则),表单会在字段上方和该字段处注明:Keep yours 会在保存时移除表单的字段;Use the form’s 保留表单的字段,以后不再询问。在 Custom fields 中,你的字段会有 Clashes with 标签,点击可在该字段处打开表单。
  • 保存时会清理。 当表单不再使用它创建的某个自定义字段时(因为你删除了该字段、修改了测试 ID,或选择了你自己的),保存前会先询问:把它移到新的测试 ID、删除它,还是保留它。如果只有负责人能修改自定义字段,成员会请负责人删除它。

你的智能体用 save_signup_form 也是这样:返回结果中的 fields_filled_by 说明每个字段由什么填写,clashes 和 leftovers 等你来决定。你的智能体会询问你,然后用 choices 或 tidy 重新保存。在此之前不会删除任何东西。

对于你自己的某个问题,如果已有自定义字段能回答,比如团队需要多少席位,从 Add a field → Your custom fields 添加即可。表单会把该字段放进代码、测试和预览中;每次填写时仍由你的自定义字段决定填什么。该字段使用自定义字段的名称,如果自定义字段按测试 ID 查找字段,还会使用该测试 ID;你可以选择文本框、下拉菜单或勾选框。字段会说明你的自定义字段能否找到它;如果新的标签或测试 ID 导致找不到,会说明自定义字段在找什么。

你的智能体用分类 custom、来自 list_custom_fields 的自定义字段 ID、标签和 options.type 来添加;fields_filled_by 中的 finds 说明自定义字段能否找到它。现成字段不这样添加:请使用该字段自己的分类。

有截图?Copy prompt 会给你一行文字,连同截图一起粘贴到你的编程智能体中:由你的智能体读取截图,截图永远不会发送到 Proxy Mail QA。Open in 会打开 Qoder、Cursor、VS Code(1.140 或更高版本)或 Claude,并已填好这行文字:在那里添加截图,然后发送。在你发送之前不会发送任何东西。如果你从其中某个工具把 Proxy Mail QA 连接到了这个项目,它会有自己的按钮,例如 Open in Qoder。

从八个规格中选一个开始,而不是空白表单。你的智能体可以用 list_signup_starters 列出它们,应用里的 New form 也会提供。

模板 要填写的内容
b2c 面向消费者的应用:姓名、邮箱、密码、出生日期、条款和可选的营销勾选框
b2b B2B SaaS:先创建账号,然后填写公司名称、网站、职位、团队规模、国家、VAT 和公司注册号
education 中性的年龄问题(填出生日期,而不是“你是否已满 13 岁?”),以及年龄较小学习者的家长邮箱
marketplace 卖家账号,然后填写其业务信息:类型、国家、地址、出生日期、税号和收款账号
travel 航空公司提前发送的旅客信息(APIS),使用 ICAO 虚构国家 Utopia 的护照及其有效期
fintech 美国身份核验所需信息:法定姓名、出生日期、电话、地址和国民身份号码
japan 日文表单:先填姓,然后是片假名读音,再填邮箱、密码、出生日期、电话和地址
china 中文表单:先填手机号,然后是密码、姓名和用于实名制的居民身份证号

每个模板都附有说明,例如 Google 登录或 LINE 按钮放在哪里(它们不是字段),以及哪些值来自支付服务商的测试模式。要其他语言或国家的版本,标签、下拉菜单和证件号格式会随之调整。在你保存自己的版本之前不会保存任何东西。

对于金融科技表单,把模板与 KYC 沙盒模式配合使用:form_values 搭配 kyc_sandbox 会给出服务商自己的沙盒值(Stripe、Plaid、Onfido、Veriff、Didit、Cashfree 或 Setu),用于通过、失败或人工审核,生成的新地址会使用该服务商的姓名和出生日期。Proxy Mail QA 从不核验身份:这些值只是与各服务商沙盒的预期相匹配。参见 各国字段格式。

{
"name": "Main sign-up",
"site": "https://staging.example.com/*",
"language": "en",
"screens": [
{
"path": "/signup",
"fields": [
{ "section": "email" },
{ "section": "password", "options": { "min_length": 12, "classes": ["upper", "digit"] } },
{ "section": "business.team_size", "options": { "choices": ["1-10", "11-50", "51-200"] } },
{ "section": "consent.terms" }
]
}
]
}
部分 说明
name 表单的名称。用相同名称保存表单会修改它
site 表单所在的网站,与项目中列出的一致。留空则在所有网站上匹配表单的字段
language 表单的语言,用于默认标签:en、de、fr、es、it、pt、nl、zh 或 ja
country 两个字母的国家代码,用于依赖国家的字段:证件号、VAT 号码、电话和地址
screens 最多 10 个按顺序排列的页面,每个页面可选 title、path,最多 30 个字段;总共 60 个字段
字段 其 section、required(除非另行指定,否则为 true)、label、testid 和 options;每个分类只能用一次

字段的标签默认是其所属部分在表单语言中的标签,测试 id 默认是 signup- 加上用短横线连接的部分 id,例如 signup-business-team-size。

部分为 custom 的字段则指向你的某个自定义字段,例如 { "section": "custom", "custom_field": "<its id>", "label": "Seats", "options": { "type": "select", "choices": ["1-5", "6-20"] } }。它需要一个标签,测试 id 默认是 signup- 加上用短横线连接的标签,例如 signup-seats。

只有接受选项的部分才有选项:密码用 min_length、max_length 和 classes(lower、upper、digit、symbol),出生日期用 min_age,随国家变化的字段用 country,下拉菜单或单选组用 choices。

get_signup_form 和 GET /v1/project/signup-forms/{id} 说明每个字段如何取值:

填写 含义
built_in form_values 和 Proxy Mail QA for Chrome 用测试人物的信息填写:姓名、邮箱、密码
custom_field 由自定义字段填写:现成的字段,或者对于部分 custom,由该字段指向的自定义字段填写
never Proxy Mail QA 留给你的测试填写

只有 custom_field 部分会用自定义字段,而且是现成的:电话、身份证号和税号、性别、语言、从哪里了解到你、职位、团队规模、业务类型和条款勾选框。表单会优先使用项目自己已有的现成字段,例如负责人在 Project settings → Custom fields 中添加的身份证号和税号字段,或用 update_project 的 fill_id_fields 一次添加全部五个。表单创建的每个字段都按测试 id 找到对应字段,所以请在表单中加上这些 data-testid 属性。删除表单时会保留它的自定义字段,除非你要求一并删除:在应用中,删除对话框里勾选 同时删除它创建的自定义字段;智能体和 API 发送 remove_custom_fields。其他表单仍在使用的自定义字段会保留。如果只有负责人能修改自定义字段,成员删除时会改为请负责人删除(同时请负责人删除它创建的自定义字段),每个字段一条请求,负责人在 Project settings → Custom fields 中处理。除此之外,别人添加的自定义字段会保留。

你的智能体可以用 get_signup_form_code 把已保存的表单转成你应用的代码,有三种类型:

格式 你会得到什么
react-hook-form 使用 react-hook-form 和 zod schema 的 React 组件(默认)
react 使用普通 state、不依赖其他包的 React 组件
html 自带脚本的单个 HTML 页面

每个字段都按规格检查:密码规则、出生日期对应的年龄,以及身份证号或增值税号在其国家的格式和校验位。提示信息和按钮使用表单的语言。多个页面依次显示,带有“下一步”和“上一步”。每个字段都保留 data-testid,表单的自定义字段因此能找到它。

身份证号检查在浏览器中运行,方便用户输入时纠正。请在服务器上也做检查。

你的智能体会让代码适配你的应用:使用你的组件和样式,同时保留测试 id 和规则。返回结果中的 notes 会说明需要检查的地方,例如下拉菜单仍然提供我们的默认选项。

get_signup_form_test 为已保存的表单生成测试,支持 Playwright(默认)或 Cypress。每个字段逐一获得表单应接受和应拒绝的值,其他字段都正确填写:

  • 字段必填时留空
  • 不含 @ 或 @ 后没有点的邮箱地址
  • 少一个字符的密码,以及分别缺少规格要求的每类字符的密码
  • 明天才满最低年龄的人的出生日期,以及今天刚满的人的出生日期
  • 校验位错误、少一个字符或在该填数字处填了字母的身份证号或增值税号
  • 带重音符号和撇号的姓名,以及其他写法的电话号码,表单应当接受

测试开始前会创建一个带人物信息和密码的测试地址,结束后删除。测试通过代码导出写入的 data-testid 找到每个字段,并期望拒绝结果显示为字段的 <test id>-error 消息或 aria-invalid="true"。把 SIGNUP_URL 设为表单所在的页面。如果你的表单不是用代码导出生成的,请检查测试 id 和错误消息是否一致,或修改测试的辅助函数。

Proxy Mail QA 无法给出值的字段(例如增值税号)会在 notes 中列出:在测试的 valid() 中填入一个你的表单接受的值。

如果只有负责人能修改自定义字段,成员的保存操作(无论在应用中还是通过其智能体)会作为整个表单的一条请求发给负责人。在应用中按钮显示为 请负责人处理。表单作为草稿等待,仍可查看和修改。负责人在 Project settings → Custom fields 中批准或拒绝;批准后会同时保存表单并创建其自定义字段。

适用于 内容
MCP list_signup_starters, list_signup_forms, get_signup_form, save_signup_form, delete_signup_form, get_signup_form_code, get_signup_form_test
REST API GET /v1/signup-starters、GET 和 POST /v1/project/signup-forms、GET 和 DELETE /v1/project/signup-forms/{id}、GET /v1/project/signup-forms/{id}/code 和 /test
npm signupStarters({ id?, language?, country? }), signupForms(), signupForm(id), saveSignupForm(spec, id?), deleteSignupForm(id, { removeCustomFields? }), signupFormCode(id, { format?, requested? }), signupFormTest(id, { framework? })
Python list_signup_starters(starter_id=None), list_signup_forms(), get_signup_form(form_id), save_signup_form(spec, form_id=None), delete_signup_form(form_id, remove_custom_fields=False), signup_form_code(form_id, format=...), signup_form_test(form_id, framework=...)

对本页有疑问?

可以用任何语言提问。文档可以立即回答,你也可以把问题发给 Proxy Mail QA 团队,他们会用英文回复。