Formularios de registro: guarda tu formulario como spec
Traducido automáticamente del inglés.
Leer en inglésUna especificación de formulario de registro indica qué pide tu formulario, pantalla por pantalla: la sección de cada campo del catálogo de campos, su etiqueta, si es obligatorio y su test id. Crea una en la app, o con tu agente de programación a partir de lo que describas o de una captura de pantalla de tu formulario, y guárdala en el proyecto. Al guardarla se usan los campos personalizados que ya rellenan sus campos y se crean los que necesita donde no hay ninguno, así que form_values rellena todos los campos que puede de forma segura y deja el resto para tu prueba.
Un proyecto guarda hasta 20 formularios de registro.
Crea una con tu agente
Sección titulada «Crea una con tu agente»Pide a tu agente que ejecute el prompt build_signup_form_from_screenshot y luego comparte una captura de cada pantalla de tu formulario. Lee los campos, te muestra la spec como una tabla para que la corrijas y solo la guarda cuando dices que sí.
Las capturas se quedan con tu agente: solo la spec que apruebas se envía a Proxy Mail QA.
También puedes describir el formulario: “email, contraseña, tamaño de la empresa y la casilla de términos, luego una segunda pantalla con tu rol”.
Crea una en la app
Sección titulada «Crea una en la app»Abre Project settings → Forms y elige Nuevo formulario. Empieza desde una plantilla o un formulario en blanco y luego:
- Añade campos del catálogo a cada pantalla, cambia sus etiquetas y márcalos como obligatorios o no
- Configura las opciones de un campo en su botón de opciones: la longitud de la contraseña y los caracteres que necesita, una edad mínima, un país o las opciones que ofrece un desplegable
- Añade pantallas, cada una con su encabezado y su ruta de página
- Míralo en Vista previa, su código en Código y sus pruebas en Pruebas, cada uno con Copiar
Las etiquetas que dejes vacías siguen el idioma del formulario. Cada campo indica cómo se rellena: por Proxy Mail QA, por un campo personalizado predefinido o por tu prueba. Una vez guardado el formulario, un campo rellenado por un campo personalizado lo nombra, con Abrir para ir a él en Project settings → Custom fields, e indica cuándo ese campo personalizado está desactivado. Un campo que uno de tus Campos estándar desactiva lo indica, con un botón para ir a ellos. Un campo de teléfono, de ID o de número fiscal, una opción o la casilla de términos se rellena con un campo predefinido: el que crea el formulario, por su test ID, o el propio del proyecto para ese tipo de campo. Un campo de teléfono indica cuándo lo escribe tu prueba: el Número de teléfono del proyecto pone un número reservado para ficción en el Reino Unido, Australia, EE. UU. y Canadá, o el número de prueba de tu app para otro país, y lo deja vacío para un país sin ninguno de los dos.
En Campos personalizados, cada campo personalizado que creó un formulario tiene una etiqueta De con el nombre del formulario, que abre el formulario. Uno tuyo que un formulario usa tal cual tiene una etiqueta Usado por.
Los formularios y tus campos personalizados
Sección titulada «Los formularios y tus campos personalizados»Un formulario describe tu página de registro: sus pantallas, campos, etiquetas y test ids, para su código, sus pruebas y su vista previa. Los campos personalizados deciden qué va en un campo en cada relleno, haya o no formulario. Un formulario nunca necesita un segundo campo personalizado para el mismo campo:
- Usa lo que hay. Donde uno de tus campos personalizados ya rellena un campo, como el Número de teléfono predefinido del proyecto o tu propia regla para una pregunta de tamaño de empresa, al guardar se usa. Solo crea uno predefinido donde nada rellena el campo.
- Nunca se impone al tuyo en silencio. Si un campo predefinido que creó el formulario prevalece sobre uno de tus campos personalizados (por ejemplo, si añadiste tu propia regla después de guardar el formulario), el formulario lo indica encima de sus campos y en el campo: Conservar el tuyo elimina el del formulario al guardar; Usar el del formulario conserva el del formulario y no vuelve a preguntar. En Campos personalizados, tu campo tiene una etiqueta Entra en conflicto con que abre el formulario en ese campo.
- Al guardar se ordena. Cuando el formulario ya no usa un campo personalizado que creó, porque eliminaste su campo, cambiaste su test id o elegiste el tuyo, al guardar pregunta primero: moverlo al nuevo test id, eliminarlo o conservarlo. Donde solo los responsables cambian los campos personalizados, un miembro pide a los responsables que lo eliminen.
Tu agente hace lo mismo con save_signup_form: el fields_filled_by de la respuesta indica qué rellena cada campo, y clashes y leftovers esperan a que decidas. Tu agente te pregunta y luego vuelve a guardar con choices o tidy. No se elimina nada hasta entonces.
Una pregunta que responde tu campo personalizado
Sección titulada «Una pregunta que responde tu campo personalizado»Para una pregunta propia que uno de tus campos personalizados ya responde, como cuántas plazas necesita un equipo, añádela desde Add a field → Your custom fields. El formulario pone el campo en su código, sus pruebas y su vista previa; tu campo personalizado sigue decidiendo qué va en él en cada relleno. El campo toma el nombre del campo personalizado y, donde el campo personalizado encuentra campos por test id, ese test id; elige si es un cuadro de texto, un desplegable o una casilla. El campo indica si tu campo personalizado lo encuentra y, si una nueva etiqueta o test id hace que no lo encuentre, qué busca el campo personalizado.
Tu agente añade uno con la sección custom, el id del campo personalizado de list_custom_fields, una etiqueta y options.type; finds en fields_filled_by indica si el campo personalizado lo encuentra. Un campo predefinido no se añade así: usa la sección propia de su campo.
¿Tienes capturas? Copiar prompt te da una línea para pegar en tu agente de programación junto con ellas: tu agente las lee y nunca llegan a Proxy Mail QA. Abrir en abre Qoder, Cursor, VS Code (1.140 o posterior) o Claude con la línea ya escrita: añade ahí tus capturas y luego envíala. No se envía nada hasta que lo hagas. Si conectaste Proxy Mail QA a este proyecto desde uno de ellos, tiene su propio botón, como Abrir en Qoder.
Plantillas
Sección titulada «Plantillas»Empieza desde una de ocho specs en lugar de un formulario en blanco. Tu agente las lista con list_signup_starters, y Nuevo formulario en la app las ofrece.
| Plantilla | Qué pide |
|---|---|
b2c |
Una app de consumo: nombre, email, contraseña, fecha de nacimiento, los términos y una casilla opcional de marketing |
b2b |
SaaS B2B: primero una cuenta, luego el nombre de la empresa, sitio web, rol, tamaño del equipo, país, IVA y número de empresa |
education |
Una pregunta de edad neutral (la fecha de nacimiento, no “¿Tienes más de 13 años?”) y el email de un padre o madre para estudiantes más jóvenes |
marketplace |
La cuenta de un vendedor y luego su negocio: tipo, país, dirección postal, fecha de nacimiento, número fiscal y cuenta de pagos |
travel |
Los datos de pasajeros que las aerolíneas envían por adelantado (APIS), con un pasaporte de Utopia, el estado ficticio de la OACI, y su fecha de vencimiento |
fintech |
Lo que necesita una verificación de identidad, para EE. UU.: nombre legal, fecha de nacimiento, teléfono, dirección postal y un número de identificación nacional |
japan |
Un formulario japonés: primero el apellido, la lectura en katakana y luego email, contraseña, fecha de nacimiento, teléfono y dirección postal |
china |
Un formulario chino: primero el teléfono, luego contraseña, nombre completo y el número de identificación de residente para la norma de nombre real |
Cada una incluye notas, como dónde van los botones de Iniciar sesión con Google o LINE (no son campos) y qué valores vienen del modo de prueba de un proveedor de pagos. Pide una en otro idioma o país, y sus etiquetas, desplegables y formatos de ID se adaptan. No se guarda nada hasta que guardes tu versión.
Para un formulario fintech, combina la plantilla con el modo sandbox de KYC: form_values con kyc_sandbox da los valores del propio sandbox de un proveedor (Stripe, Plaid, Onfido, Veriff, Didit, Cashfree o Setu) para un aprobado, un rechazo o una revisión, y la nueva dirección que crea toma los nombres y la fecha de nacimiento del proveedor. Proxy Mail QA nunca verifica una identidad: los valores solo coinciden con lo que espera el sandbox de cada proveedor. Consulta Formatos de campo por país.
Qué contiene una spec
Sección titulada «Qué contiene una spec»{ "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" } ] } ]}| Parte | Qué dice |
|---|---|
name |
Cómo se llama el formulario. Guardar un formulario con el mismo nombre lo modifica |
site |
El sitio en el que está, tal como lo lista el proyecto. Omítelo para que los campos del formulario coincidan en todos los sitios |
language |
El idioma del formulario, para sus etiquetas predeterminadas: en, de, fr, es, it, pt, nl, zh o ja |
country |
Un código de país de dos letras para los campos que dependen de uno: IDs, números de IVA, teléfonos y direcciones postales |
screens |
Hasta 10 pantallas en orden, cada una con un title y un path opcionales y hasta 30 campos; 60 campos en total |
| Un campo | Su section, required (true salvo que indiques lo contrario), label, testid y options; cada sección una vez |
La etiqueta de un campo es, por defecto, la etiqueta de su sección en el idioma del formulario, y su test id es signup- y el id de la sección con guiones, como signup-business-team-size.
Un campo con la sección custom nombra en cambio uno de tus campos personalizados, como { "section": "custom", "custom_field": "<its id>", "label": "Seats", "options": { "type": "select", "choices": ["1-5", "6-20"] } }. Necesita una etiqueta, y su test id es, por defecto, signup- y la etiqueta con guiones, como signup-seats.
Las opciones son solo para las secciones que las admiten: min_length, max_length y classes (lower, upper, digit, symbol) para una contraseña, min_age para una fecha de nacimiento, country para un campo que depende del país y choices para una lista desplegable o un grupo de opciones.
Cómo se llena cada campo
Sección titulada «Cómo se llena cada campo»get_signup_form y GET /v1/project/signup-forms/{id} indican cómo obtiene su valor cada campo:
| Llenado | Significado |
|---|---|
built_in |
form_values y Proxy Mail QA for Chrome lo llenan con los datos de la persona de prueba: nombres, correo, contraseña |
custom_field |
Lo llena un campo personalizado: uno predefinido o, para la sección custom, el que nombra el campo |
never |
Proxy Mail QA lo deja para tu prueba |
Solo las secciones custom_field reciben un campo personalizado, uno predefinido: teléfono, números de identificación y fiscales, género, idioma, cómo te conoció la persona, cargo, tamaño del equipo, tipo de negocio y la casilla de términos. Un formulario usa los campos predefinidos del propio proyecto cuando los tiene, como los campos de número de identificación y fiscal que un líder agrega en Project settings → Custom fields, o los cinco a la vez con fill_id_fields de update_project. Cada uno que crea un formulario encuentra su campo por el test id, así que agrega esos atributos data-testid a tu formulario. Al eliminar un formulario se conservan sus campos personalizados, salvo que pidas eliminarlos también: en la app, Eliminar también los campos personalizados que creó está marcado en el diálogo Eliminar; los agentes y API envían remove_custom_fields. Un campo personalizado que otro formulario todavía usa se conserva. Donde solo los líderes cambian los campos personalizados, la eliminación hecha por un miembro pide a los líderes que los eliminen (Pedir también a los líderes que eliminen los campos personalizados que creó), una solicitud por cada uno, que responden en Project settings → Custom fields. En los demás casos, un campo personalizado que agregó otra persona se conserva.
Obtenlo como código
Sección titulada «Obtenlo como código»Tu agente puede convertir un formulario guardado en código para tu app con get_signup_form_code, de uno de tres tipos:
| Formato | Qué obtienes |
|---|---|
react-hook-form |
Un componente de React con react-hook-form y un esquema de zod (por defecto) |
react |
Un componente de React con estado simple y sin otros paquetes |
html |
Una página HTML con su propio script |
Cada campo comprueba lo que pide la especificación: las reglas de la contraseña, la edad en una fecha de nacimiento, y el formato y el dígito de control de un número de identificación o de IVA según su país. Los mensajes y botones están en el idioma del formulario. Las pantallas se muestran una tras otra, con Siguiente y Atrás. Cada campo conserva su data-testid, así que los campos personalizados del formulario lo encuentran.
Las comprobaciones de identificación se ejecutan en el navegador para ayudar a las personas mientras escriben. Compruébalas también en tu servidor.
Tu agente adapta el código a tu app: tus componentes y estilos, conservando los test ids y las reglas. Las notes de la respuesta indican qué revisar, como una lista desplegable que todavía ofrece nuestras respuestas habituales.
Obtén pruebas
Sección titulada «Obtén pruebas»get_signup_form_test genera pruebas para un formulario guardado, para Playwright (por defecto) o Cypress. Cada campo recibe valores que el formulario debe aceptar y valores que debe rechazar, uno a la vez, con todos los demás campos llenados correctamente:
- Vacío, cuando el campo es obligatorio
- Una dirección de correo sin @, o sin punto después
- Una contraseña con un carácter de menos, y una sin cada tipo de carácter que pide la especificación
- Una fecha de nacimiento de alguien que cumple la edad mínima mañana, y una de alguien que la cumplió hoy
- Un número de identificación o de IVA con el dígito de control incorrecto, con un carácter de menos o con una letra donde va un dígito
- Nombres con tildes y apóstrofos, y números de teléfono escritos de otras formas, que el formulario debe aceptar
Las pruebas crean una dirección de prueba con una persona y una contraseña antes de empezar, y la eliminan al final. Encuentran cada campo por el data-testid que escribe la exportación de código, y esperan que un rechazo se muestre como el mensaje <test id>-error del campo o aria-invalid="true". Configura SIGNUP_URL con la página del formulario. Si tu formulario no se creó con la exportación de código, comprueba que sus test ids y mensajes de error coincidan, o cambia los helpers de la prueba.
Un campo para el que Proxy Mail QA no da ningún valor, como un número de IVA, se nombra en notes: pon un valor que tu formulario acepte en valid() de la prueba.
En un proyecto bloqueado
Sección titulada «En un proyecto bloqueado»Donde solo los líderes cambian los campos personalizados, el guardado de un miembro, en la app o mediante su agente, llega a los líderes como una sola solicitud para todo el formulario. En la app el botón dice Pedir a los líderes. El formulario espera como borrador, que todavía se puede leer y cambiar. Un líder lo aprueba o lo rechaza en Project settings → Custom fields; al aprobarlo se guarda el formulario y se crean sus campos personalizados a la vez.
| Dónde | Qué |
|---|---|
| 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 y POST /v1/project/signup-forms, GET y DELETE /v1/project/signup-forms/{id}, GET /v1/project/signup-forms/{id}/code y /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=...) |
¿Tienes una pregunta sobre esta página?
Pregunta en cualquier idioma. La documentación puede responderte de inmediato, o puedes enviar tu pregunta al equipo de Proxy Mail QA, que responde en inglés.