Forms: Allow submitting form previews as test responses

Form preview now lets you submit the form to test the full submission
flow end to end. Responses created from preview are stored normally in
the inbox but flagged as test responses: clearly badged in the dashboard
list and detail panel, prefixed with [TEST] in the notification email
with a banner, excluded from the default CSV export, and excluded from
exports unless explicitly selected.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: enejb

projects/packages/forms/changelog/add-forms-preview-submissions

@@ -0,0 +1,4 @@
+Significance: minor
+Type: added
+
+Form preview now lets you submit the form to test the full submission flow end to end. Responses created from preview are stored as test responses, clearly flagged in the notification email, and excluded from the default CSV export.

projects/packages/forms/routes/responses/stage.tsx

@@ -145,6 +145,38 @@ function getUrlPath( url: string ): string | null {
 	}
 }
 
+/**
+ * Badge surfacing that a response came from form preview.
+ *
+ * When a preview URL is available, the badge is wrapped in a link pointing
+ * to the preview so the form owner can re-open it. Otherwise it renders as
+ * a plain label.
+ *
+ * @param props            - Component props.
+ * @param props.previewUrl - URL to the form preview, or null/undefined.
+ * @return The badge element.
+ */
+function FormPreviewBadge( { previewUrl }: { previewUrl?: string | null } ) {
+	const label = __( 'Form Preview', 'jetpack-forms' );
+	const badge = <Badge intent="none">{ label }</Badge>;
+
+	if ( ! previewUrl ) {
+		return badge;
+	}
+
+	return (
+		<a
+			href={ previewUrl }
+			target="_blank"
+			rel="noreferrer"
+			style={ { textDecoration: 'none' } }
+			aria-label={ __( 'Open form preview in a new tab', 'jetpack-forms' ) }
+		>
+			{ badge }
+		</a>
+	);
+}
+
 /**
  * Stage component for the form responses DataViews.
  *
@@ -432,9 +464,14 @@ function StageInner() {
 							/>
 							{ styleUnreadValue(
 								<Stack direction="column" gap="2xs">
-									<Text ellipsizeMode="tail" limit={ 50 } truncate>
-										{ displayName }
-									</Text>
+									<Stack direction="row" align="center" gap="xs">
+										{ item.is_test && (
+											<Badge intent="informational">{ __( 'Test', 'jetpack-forms' ) }</Badge>
+										) }
+										<Text ellipsizeMode="tail" limit={ 50 } truncate>
+											{ displayName }
+										</Text>
+									</Stack>
 									{ showEmail && (
 										<Text variant="muted" size={ 12 } ellipsizeMode="tail" limit={ 50 } truncate>
 											{ item.author_email }
@@ -479,6 +516,14 @@ function StageInner() {
 				id: 'source',
 				label: __( 'Source', 'jetpack-forms' ),
 				render: ( { item } ) => {
+					// Test responses (submitted from form preview) don't point at a
+					// real source page — surface a Form Preview badge in place of the link.
+					if ( item.is_test ) {
+						return styleUnreadValue(
+							<FormPreviewBadge previewUrl={ item.preview_url } />,
+							item.is_unread
+						);
+					}
 					const source =
 						item.entry_title ||
 						getUrlPath( item.entry_permalink ) ||

projects/packages/forms/src/contact-form/class-contact-form-endpoint.php

@@ -807,6 +807,26 @@ public function get_item_schema() {
 			'readonly'    => true,
 		);
 
+		$schema['properties']['is_test'] = array(
+			'description' => __( 'Whether the form response was submitted from a form preview (test response).', 'jetpack-forms' ),
+			'type'        => 'boolean',
+			'context'     => array( 'view', 'edit', 'embed' ),
+			'arg_options' => array(
+				'sanitize_callback' => 'rest_sanitize_boolean',
+			),
+			'readonly'    => true,
+		);
+
+		$schema['properties']['preview_url'] = array(
+			'description' => __( 'URL to the form preview that produced this response, when the response is a test submission.', 'jetpack-forms' ),
+			'type'        => array( 'string', 'null' ),
+			'context'     => array( 'view', 'edit', 'embed' ),
+			'arg_options' => array(
+				'sanitize_callback' => 'esc_url_raw',
+			),
+			'readonly'    => true,
+		);
+
 		$this->schema = $schema;
 
 		return $this->add_additional_fields_schema( $this->schema );
@@ -988,6 +1008,21 @@ public function prepare_item_for_response( $item, $request ) {
 			$data['is_unread'] = $feedback_response->is_unread();
 		}
 
+		if ( rest_is_field_included( 'is_test', $fields ) ) {
+			$data['is_test'] = $feedback_response->is_test();
+		}
+
+		if ( rest_is_field_included( 'preview_url', $fields ) ) {
+			$preview_url = null;
+			if ( $feedback_response->is_test() ) {
+				$form_id = $feedback_response->get_form_id();
+				if ( $form_id ) {
+					$preview_url = Form_Preview::generate_preview_url( (int) $form_id );
+				}
+			}
+			$data['preview_url'] = $preview_url;
+		}
+
 		$response->set_data( $data );
 
 		return rest_ensure_response( $response );

projects/packages/forms/src/contact-form/class-contact-form-plugin.php

@@ -1607,11 +1607,6 @@ public static function recalculate_unread_count() {
 	 * Conditionally attached to `template_redirect`
 	 */
 	public function process_form_submission() {
-		// Block submissions in preview mode.
-		if ( Form_Preview::is_preview_mode() ) {
-			return;
-		}
-
 		// Add a filter to replace tokens in the subject field with sanitized field values.
 		add_filter( 'contact_form_subject', array( $this, 'replace_tokens_with_input' ), 10, 2 );
 
@@ -1625,6 +1620,24 @@ public function process_form_submission() {
 			return Form_Submission_Error::system_error( 'invalid_form_id_or_hash', __( 'Invalid form ID or hash.', 'jetpack-forms' ) );
 		}
 
+		// Detect and authorize submissions coming from form preview. When a preview
+		// submission is detected we let it flow through the normal pipeline but
+		// flag the resulting feedback as a test response.
+		$is_preview_submission = false;
+		// phpcs:ignore WordPress.Security.NonceVerification.Missing -- the nonce is verified inside verify_preview_submission().
+		if ( ! empty( $_POST[ Form_Preview::PREVIEW_SUBMIT_FIELD ] ) ) {
+			$preview_form_id = is_numeric( $id ) ? (int) $id : 0;
+			if ( $preview_form_id > 0 && Form_Preview::verify_preview_submission( $preview_form_id ) ) {
+				$is_preview_submission = true;
+			} else {
+				// Preview flag was present but nonce/caps did not check out. Reject.
+				return Form_Submission_Error::system_error(
+					'invalid_preview_submission',
+					__( 'Invalid form preview submission.', 'jetpack-forms' )
+				);
+			}
+		}
+
 		if ( is_user_logged_in() ) {
 			check_admin_referer( "contact-form_{$id}" );
 		}
@@ -1721,6 +1734,9 @@ public function process_form_submission() {
 			if ( Jetpack_Forms::is_webhooks_enabled() && ! empty( $form->attributes['webhooks'] ) ) {
 				Form_Webhooks::init();
 			}
+			// Flag the submission as originating from a form preview so the form
+			// treats the resulting feedback as a test response.
+			$form->set_is_preview_submission( $is_preview_submission );
 			// Process the form
 			return $form->process_submission();
 		}
@@ -1909,6 +1925,10 @@ public function process_form_submission() {
 			Form_Webhooks::init();
 		}
 
+		// Flag the submission as originating from a form preview so the form
+		// treats the resulting feedback as a test response.
+		$form->set_is_preview_submission( $is_preview_submission );
+
 		// Process the form
 		return $form->process_submission();
 	}
@@ -2906,11 +2926,14 @@ public function personal_data_search_filter( $search ) {
 	/**
 	 * Returns an array of feedback data for export.
 	 *
-	 * @param array $feedback_ids Array of feedback IDs to fetch the data for.
+	 * @param array $feedback_ids           Array of feedback IDs to fetch the data for.
+	 * @param bool  $include_test_responses Whether to include feedback that was submitted
+	 *                                      from form preview. Defaults to false, meaning
+	 *                                      preview/test responses are excluded from the export.
 	 *
 	 * @return array
 	 */
-	public function get_export_feedback_data( $feedback_ids ) {
+	public function get_export_feedback_data( $feedback_ids, $include_test_responses = false ) {
 		$feedback_data   = array();
 		$all_field_names = array();
 
@@ -2921,6 +2944,11 @@ public function get_export_feedback_data( $feedback_ids ) {
 				continue; // Skip if the feedback is not an instance of Feedback.
 			}
 
+			// Skip test responses from form preview unless explicitly requested.
+			if ( ! $include_test_responses && $response->is_test() ) {
+				continue;
+			}
+
 			// Get fields with automatic duplicate handling (label-value shape includes counts)
 			$compiled_fields = $response->get_compiled_fields( 'csv', 'label-value' );
 
@@ -3078,7 +3106,8 @@ public function get_feedback_entries_from_post() {
 			}
 		}
 
-		if ( ! empty( $_POST['selected'] ) && is_array( $_POST['selected'] ) ) {
+		$has_explicit_selection = ! empty( $_POST['selected'] ) && is_array( $_POST['selected'] );
+		if ( $has_explicit_selection ) {
 			$args['include'] = array_filter(
 				array_map(
 					function ( $selected ) {
@@ -3091,7 +3120,11 @@ function ( $selected ) {
 
 		$feedbacks = get_posts( $args );
 
-		return $this->get_export_feedback_data( $feedbacks );
+		// Test responses from form preview are excluded from bulk exports by
+		// default. When the user has explicitly picked specific rows (via the
+		// dashboard selection UI), we trust their selection and include any
+		// test responses that landed in it.
+		return $this->get_export_feedback_data( $feedbacks, $has_explicit_selection );
 	}
 
 	/**

projects/packages/forms/src/contact-form/class-contact-form.php

@@ -137,6 +137,17 @@ class Contact_Form extends Contact_Form_Shortcode {
 	 */
 	public $has_verified_jwt = false;
 
+	/**
+	 * Whether the current submission originated from an authenticated form preview.
+	 *
+	 * When true, the resulting feedback is marked as a test submission — Akismet
+	 * is skipped, the notification email is annotated, and the response is
+	 * excluded from the default CSV export.
+	 *
+	 * @var bool
+	 */
+	private $is_preview_submission = false;
+
 	/**
 	 * The source of the feedback entry.
 	 *
@@ -619,6 +630,25 @@ public function set_source( $source ) {
 		$this->source = $source;
 	}
 
+	/**
+	 * Flag whether the current submission originated from an authenticated form preview.
+	 *
+	 * @param bool $is_preview_submission Whether the submission came from form preview.
+	 * @return void
+	 */
+	public function set_is_preview_submission( $is_preview_submission ) {
+		$this->is_preview_submission = (bool) $is_preview_submission;
+	}
+
+	/**
+	 * Whether the current submission is a test submission coming from form preview.
+	 *
+	 * @return bool
+	 */
+	public function is_preview_submission() {
+		return $this->is_preview_submission;
+	}
+
 	/**
 	 * Get the context for the contact form based on the attributes and post.
 	 *
@@ -1249,7 +1279,6 @@ public static function parse( $attributes, $content, $context = array() ) {
 				'invalid_form_empty' => __( 'The form you are trying to submit is empty.', 'jetpack-forms' ),
 				'invalid_form'       => __( 'Please fill out the form correctly.', 'jetpack-forms' ),
 				'network_error'      => __( 'Connection issue while submitting the form. Check that you are connected to the Internet and try again.', 'jetpack-forms' ),
-				'preview_mode'       => __( 'Form submissions are disabled in preview mode.', 'jetpack-forms' ),
 			),
 			'admin_ajax_url' => admin_url( 'admin-ajax.php' ),
 		);
@@ -2602,6 +2631,16 @@ public function process_submission() {
 
 		$response = Feedback::from_submission( $_POST, $this ); // phpcs:Ignore WordPress.Security.NonceVerification.Missing
 		$response->set_source( $this->get_source() );
+
+		// If the submission came from an authenticated form preview, flag the
+		// feedback as a test submission. The rest of the pipeline reads the
+		// flag from the feedback (which also travels into the serialized
+		// post_content via Feedback_Source).
+		if ( $this->is_preview_submission ) {
+			$response->mark_as_test();
+		}
+		$is_test_submission = $response->is_test();
+
 		$plugin = Contact_Form_Plugin::init();
 
 		$id                  = $this->get_attribute( 'id' );
@@ -2692,9 +2731,15 @@ public function process_submission() {
 		$spam           = '';
 		$akismet_values = $plugin->prepare_for_akismet( $akismet_vars );
 
-		// Is it spam?
-		/** This filter is already documented in \Automattic\Jetpack\Forms\ContactForm\Admin */
-		$is_spam = apply_filters( 'jetpack_contact_form_is_spam', false, $akismet_values );
+		// Is it spam? Test submissions (from form preview) skip Akismet entirely —
+		// the form owner is explicitly running a test and we don't want Akismet
+		// to learn from synthetic data or bounce the submission.
+		if ( $is_test_submission ) {
+			$is_spam = false;
+		} else {
+			/** This filter is already documented in \Automattic\Jetpack\Forms\ContactForm\Admin */
+			$is_spam = apply_filters( 'jetpack_contact_form_is_spam', false, $akismet_values );
+		}
 		if ( is_wp_error( $is_spam ) ) { // WP_Error to abort
 			return $is_spam; // abort
 		} elseif ( $is_spam === true ) {  // TRUE to flag a spam
@@ -2790,6 +2835,22 @@ public function process_submission() {
 
 		$entry_values = $response->get_entry_values();
 
+		// Prefix the subject with [TEST] for test submissions so the form owner
+		// can immediately tell this email came from a preview-mode submission.
+		if ( $is_test_submission ) {
+			/**
+			 * Filter the subject prefix applied to test (preview) feedback emails.
+			 *
+			 * @module contact-form
+			 *
+			 * @since $$next-version$$
+			 *
+			 * @param string $prefix Default subject prefix for test submissions.
+			 */
+			$test_prefix          = apply_filters( 'jetpack_forms_test_subject_prefix', '[TEST] ' );
+			$contact_form_subject = $test_prefix . $contact_form_subject;
+		}
+
 		/** This filter is already documented in \Automattic\Jetpack\Forms\ContactForm\Admin */
 		$subject = apply_filters( 'contact_form_subject', $contact_form_subject, $all_values );
 
@@ -2901,6 +2962,7 @@ public function process_submission() {
 			'comment_author_email' => $comment_author_email,
 			'comment_author_ip'    => $comment_author_ip,
 			'is_spam'              => $is_spam,
+			'is_test'              => $is_test_submission,
 			'feedback_status'      => $feedback_status,
 		);
 		$email        = Feedback_Email_Renderer::build_email_content( $post_id, $this, $response, $context_data );
@@ -2937,6 +2999,25 @@ public function process_submission() {
 			$send_email = ( $this->get_attribute( 'emailNotifications' ) !== 'no' );
 		}
 
+		// Test submissions always send the notification email (so the form
+		// owner can verify their email flow end-to-end) regardless of the
+		// emailNotifications attribute. Site admins who want to opt out can
+		// return false from the filter below.
+		if ( $is_test_submission ) {
+			/**
+			 * Filter whether test (preview) submissions should trigger the notification email.
+			 *
+			 * @module contact-form
+			 *
+			 * @since $$next-version$$
+			 *
+			 * @param bool     $send     Whether to send the test submission email. Default true.
+			 * @param int      $post_id  The feedback post ID.
+			 * @param Feedback $response The feedback response object.
+			 */
+			$send_email = apply_filters( 'jetpack_forms_send_test_feedback_email', true, $post_id, $response );
+		}
+
 		/**
 		 * Filter to determine if spam should still be emailed.
 		 *