Ir al contenido

Traducido automáticamente del inglés.

Leer en inglés

Una 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.

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”.

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.

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.

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.

{
"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.

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.

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.

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.

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.