How to Test the Screenshot Import Feature — A Complete Guide

Formcierge includes a screenshot import feature that lets you take a picture of any form — from a website, a PDF, a design tool, or even a paper form — and have Formcierge recreate it as a fully functional, editable form on your canvas. This guide explains every import mode in detail and walks you through a complete A-to-Z testing procedure so you know exactly what to expect and how to verify that everything is working correctly.

How Screenshot Import Works

When you upload a screenshot, Formcierge sends it to an AI vision model via the /wp-json/formcierge/v1/ai/extract-form-image endpoint. The model analyses the image and returns a structured JSON object describing the detected form fields, labels, layout, and (depending on the mode) visual styles. The frontend then applies that data to the live canvas.

The flow has five stages:

1. Upload — drag-and-drop, file picker, paste from clipboard, or enter a public image URL
2. Options — choose an extraction mode (see below)
3. Extracting — AI processes the image (progress bar shown)
4. Preview — review the detected fields before applying
5. Apply — fields are written to the canvas

You can cancel at any point before the Apply stage without affecting the current form.

The Four Extraction Modes

After uploading an image, Formcierge presents four mode options. Choosing the right mode determines how much information is extracted and how it is applied.

Mode 1 — Exact Copy

What it does: The AI attempts to recreate the form as closely as possible, including field types, labels, placeholder text, layout, colours, fonts, border radius, and other visual properties visible in the screenshot.

API parameter sent: exactness=exact

When to use it: You have a competitor form or a design mockup that you want to reproduce quickly. You want the colours and visual style to match the original as closely as possible.

What gets extracted:

• All field types (text, email, select, radio, checkbox, textarea, etc.)
• Field labels and placeholder text
• Required/optional state if visually indicated (asterisk, “(required)” text)
• Multi-column row layout if visible
• Primary colour extracted from buttons and accents
• Border radius and input style (outlined, filled, underlined)
• Font style if identifiable
• Submit button label

Limitations: The AI cannot read exact hex colour values from pixels — it makes a best-effort colour match. Font family detection is approximate. Complex CSS effects (shadows, gradients, animations) are not replicated.

Mode 2 — Structure Only (Clean)

What it does: Extracts only the form structure — fields, labels, types, layout — and ignores all visual styling. The resulting form uses your currently active Formcierge theme and style settings.

API parameter sent: exactness=clean

This is the recommended default mode. It gives you the form skeleton ready to customise with your own brand styles.

When to use it: You want to capture the fields and layout from an existing form (a client’s current form, a regulatory form, a paper document) but apply your own styling on top. This is the fastest path to getting a working form from a screenshot.

What gets extracted:

• All field types and labels
• Placeholder text
• Row layout (multi-column groups)
• Required state indicators
• Select/radio/checkbox option values
• Submit button label

What is intentionally ignored: All colours, fonts, borders, spacing, and visual decoration. The canvas will show the extracted fields using your default form styles.

Mode 3 — Copy Styles Only

What it does: Extracts only the visual styling from the screenshot — colours, font style, border radius, input style — and applies those styles to your existing form on the canvas. No fields are added or removed.

API parameter sent: exactness=styles_only

When to use it: You already have a working form built in Formcierge and you want it to visually match a reference design. Upload a screenshot of the target design and apply its colour palette and style to your form without touching the fields.

What gets extracted and applied:

• Primary/accent colour (applied to buttons, focus states, borders)
• Background colour
• Label and body text colour
• Input background colour
• Border radius (inputs, buttons, sections)
• Input style variant (outlined, filled, underlined)
• Font style (sans-serif, serif, monospace — approximate)

What is intentionally ignored: All field types, labels, layout, and field count. Your existing form fields remain completely unchanged.

Important: This mode requires an existing form to be open on the canvas. If the canvas is empty, the AI will extract styles but there is nothing to apply them to. The chatbox will warn you if this happens.

Mode 4 — Smart Import

What it does: A superset of Structure Only. The AI analyses the screenshot with extra intelligence — it infers the best Formcierge field type for each input (not just a direct mapping), adds appropriate validation rules automatically (e.g., email format, phone pattern), and may suggest improvements the original form did not have.

API parameter sent: exactness=themed

When to use it: You are importing a legacy form that used generic text inputs for everything (e.g., a scanned paper form). Smart Import will upgrade a plain text “Email” field to an actual Email field with validation, a “Phone” field to a Tel field, a “Date” field to a Date picker, and so on.

What gets extracted: Same as Structure Only, plus:

• Intelligent field type inference (text → email/tel/url/number/date as appropriate)
• Automatic validation rules based on field purpose
• Suggested placeholder text improvements
• Logical grouping of related fields into Row layout

Trade-off: Smart Import may occasionally over-infer — for example, converting a “Reference Number” field to a Number input when the original used text. Always review the preview stage before applying.

How to Trigger Screenshot Import

There are four ways to start the import flow. Test all four:

1. Upload button — in the chatbox, click the image/upload icon and select a file from your computer
2. Drag and drop — drag an image file directly onto the chat input area or canvas
3. Paste from clipboard — copy an image to your clipboard (e.g., screenshot via Ctrl+Shift+S or Snipping Tool) then paste it into the chat input with Ctrl+V
4. URL import — type or paste a direct image URL (ending in .png, .jpg, .webp) into the chat input; the chatbox detects it is an image URL and offers to import it

Complete A-to-Z Testing Procedure

Work through the following steps in order. Each step has a clear pass/fail criterion.

Preparation

Before starting, prepare four test images. These can be screenshots you take of real forms or sample images:

• Image A — a simple styled contact form (coloured buttons, clear labels). Good for testing Exact Copy and Copy Styles Only.
• Image B — a complex multi-column form with selects, radio buttons, and checkboxes. Good for testing Structure Only and Smart Import.
• Image C — a scanned or low-quality image of a paper form with handwritten labels. Good for testing AI robustness.
• Image D — a non-form image (a landscape photo, a logo). Good for testing the “no form detected” error path.

Step A — Upload triggers the flow

Open the Formcierge builder. Open the chatbox. Click the image upload icon and select Image A.

Pass: The chatbox transitions to the Options stage showing all four mode cards (Exact Copy, Structure Only, Copy Styles Only, Smart Import). A thumbnail preview of the uploaded image is visible. No error appears.

Fail indicators: Page error, blank modal, “Upload failed” message, or the mode selection screen never appears.

Step B — Clipboard paste triggers the flow

Take a screenshot with your OS tool (Windows: Win+Shift+S, Mac: Cmd+Shift+4). Click into the chat input. Press Ctrl+V (Cmd+V on Mac).

Pass: The same Options stage appears with the clipboard image shown as a thumbnail preview.

Fail indicator: Ctrl+V pastes text instead of triggering the image flow — this means the paste event listener is not active on the chat input.

Step C — Drag-and-drop triggers the flow

Drag Image A from your file explorer and drop it onto the chat input area.

Pass: The Options stage appears with the image thumbnail. The drop target visually highlighted during drag (hover state).

Step D — Exact Copy mode: structure and styles

Upload Image A (styled form). Select Exact Copy. Click the extract button.

Pass:

• The progress bar advances from 0% to 100% without getting stuck
• The Preview stage shows the detected fields with labels matching the original image
• After clicking Apply, the canvas shows the fields
• The form style settings (primary colour, border radius) reflect the colours from the image (approximate match — not pixel-perfect)
• Open Form Style panel: primary colour should be visibly close to the button colour in the screenshot

What to check in the browser console: No TypeError or Cannot read properties of undefined errors. Confirm the response JSON from the API contains a styles object alongside the fields array.

Step E — Structure Only mode: fields without styles

Upload Image A again. Select Structure Only. Apply to canvas.

Pass:

• Fields are extracted and applied correctly
• The form style settings are unchanged from whatever they were before import — no colour or style overwrite occurs
• Open the Form Style panel and confirm the primary colour, border radius, and background colour match your pre-import defaults, not the screenshot image

Step F — Copy Styles Only mode: styles without field changes

First, manually build a simple form with 3 fields (Text, Email, Textarea). Note the field count and labels. Then upload Image A. Select Copy Styles Only. Apply.

Pass:

• Your 3 existing fields are still on the canvas after import — nothing was added or removed
• The form style settings (primary colour, border radius, etc.) have updated to reflect the colours from the screenshot
• Open Form Style panel and confirm the primary colour is visibly close to the accent/button colour in Image A

Fail indicator: Any existing field was removed or a new field was added — this means the styles-only mode incorrectly ran a field extraction pass.

Step G — Smart Import mode: field type upgrades

Use Image B (complex multi-column form). Select Smart Import. Apply to canvas.

Pass:

• Select/radio/checkbox fields are present as choice-type fields (not generic text)
• An email field in the original image maps to the email field type in Formcierge (not text)
• A phone field maps to tel type
• A date field maps to date type
• Related side-by-side fields (e.g., First Name + Last Name) are placed in a Row container
• At least one field has a validation rule or required flag if those were present in the original

Step H — Complex form: multi-column layout

Upload Image B using Structure Only or Smart Import. After applying, check the canvas layout.

Pass:

• Fields that appear side-by-side in the screenshot are placed inside Row containers on the canvas
• Each Row column contains the correct field
• Rows can be re-ordered by dragging without breaking the layout

Step I — Select / radio options preserved

Use a screenshot that contains a visible dropdown or radio group with readable option labels (e.g., “Small / Medium / Large”).

Pass: After import, open the field settings for that dropdown/radio. The options list should contain the values from the screenshot. If the AI could not read the options, it should produce at least one placeholder option and the chatbox should note that options may need review.

Step J — Low quality / paper form image

Upload Image C (scanned or low-quality paper form). Use Smart Import.

Pass: The AI extracts some or all fields even from a degraded image. The chatbox may display a confidence warning (e.g., “Some fields may not have been detected accurately — please review the preview”). No crash or unhandled promise rejection.

Acceptable: Fewer fields extracted than visible — the AI may miss fields in very low quality images. The key criterion is no crash and a useful preview is shown.

Step K — Non-form image detection

Upload Image D (a non-form image — landscape photo, logo, etc.).

Pass: The chatbox displays a “No form detected” message and does not apply any fields to the canvas. The canvas remains unchanged. The user can cancel or try a different image.

Fail indicator: Random fields appear on the canvas from a non-form image, or the import crashes with a JavaScript error.

Step L — Preview stage: review before applying

Upload any valid form image. At the Preview stage, do NOT click Apply yet.

Pass:

• The preview shows a list of detected fields with their types and labels
• You can read each field name clearly
• A Cancel button is accessible and, when clicked, closes the flow without modifying the canvas
• The current canvas is unaffected at this stage (no partial writes)

Step M — Apply overwrites or appends?

Have 2 existing fields on the canvas. Upload a form screenshot with 4 different fields. Select Structure Only. Apply.

Expected behaviour (verify which applies to your current build):

• Replace: Canvas is cleared and replaced with the 4 imported fields. The original 2 are gone.
• Append: The 4 imported fields are added below the 2 existing fields, giving 6 total.

Document which behaviour your build uses and confirm it is consistent across all four import modes. Inconsistency here (replace in one mode, append in another) is a bug.

Step N — Undo after import

After a successful import that adds fields, use the browser back arrow (no — this navigates away), or press Ctrl+Z, or type /undo in the chatbox.

Pass: The canvas reverts to its pre-import state. Fields added by the import are removed. Any style changes made by Exact Copy or Copy Styles Only are also reverted.

Step O — Large image file handling

Create or find a PNG screenshot that is larger than 5 MB (a very high resolution screenshot). Attempt to upload it.

Pass: Either the image is accepted and processed (large images may be slower), or a clear file size error message is displayed. The UI does not hang or display a blank loading state indefinitely.

Step P — Wrong file type

Attempt to upload a PDF, a .docx file, or a .txt file via the upload button.

Pass: A clear error message appears such as “Please upload a PNG, JPG, or WebP image.” No crash. The upload area resets to its default state.

Step Q — URL import from a valid public image

Find a publicly accessible form screenshot URL (a direct link ending in .png or .jpg). Type or paste the URL into the chat input and submit.

Pass: The chatbox detects this is an image URL (not a text prompt), transitions to the Options stage showing a preview of the image fetched from the URL, and proceeds with extraction on mode selection.

Note: The URL fetch happens server-side to avoid CORS issues — the API endpoint downloads the image then processes it. Verify the endpoint handles non-image URLs gracefully (should return an error, not crash).

Step R — Cancellation at each stage

Test cancellation at each stage:

• Cancel at Upload stage: The flow closes and the canvas is unaffected.
• Cancel at Options stage: The flow closes and the canvas is unaffected.
• Cancel during Extracting (in-flight request): The flow closes. The pending API request may continue in the background but its result must NOT be applied to the canvas. No zombie state.
• Cancel at Preview stage: The flow closes and the canvas is unaffected.

Pass for all four: Canvas state is identical before and after cancellation at each stage.

Step S — Confidence score display

After extraction, check the Preview stage for a confidence indicator. If the AI backend returns a confidence score (typically 0–1 or 0–100), the UI should display it.

Pass: A confidence percentage or label is visible (e.g., “Confidence: 87%”, or a colour-coded indicator). Low confidence triggers a warning note in the chatbox prompting the user to review carefully.

Step T — Form save after import

After a successful Exact Copy import, click Save Form (or type /save in the chatbox).

Pass: The form saves successfully and the style settings (colours, radius, etc.) extracted from the screenshot are persisted in the saved form data. Reload the form from the Forms list and confirm the imported styles are still present after reload.

Step U — Styles survive a theme change

After an Exact Copy import, open the Form Style panel and change the theme to “Dark” then back to “Custom”. Verify the imported colours have not been wiped by the theme toggle.

Pass: After switching back to Custom, the Exact Copy colours are still present in the style settings. Theme switching should not permanently destroy custom style data.

Step V — Import on mobile viewport

In Chrome DevTools, set the viewport to 375px wide (iPhone SE). Open the chatbox and trigger the screenshot import flow via the upload button.

Pass: The Options stage mode cards are readable and tappable at 375px. No horizontal overflow. The extract and apply buttons are within the viewport. The preview list is scrollable.

Step W — Network error during extraction

In Chrome DevTools → Network, set throttling to “Offline”. Upload an image and attempt extraction.

Pass: The chatbox displays a clear network error message (e.g., “Extraction failed — please check your connection and try again”). The progress bar does not stay at 50% indefinitely. The user can dismiss the error and try again.

Step X — No existing form for Styles Only

Start with a completely empty canvas (no fields). Upload any form screenshot. Select Copy Styles Only. Apply.

Pass: Either a warning is shown before applying (“Your canvas is empty — styles will be saved but will not be visible until you add fields”), or the styles are applied to the form settings silently and will take effect when fields are added. No crash. The chatbox does not become unresponsive.

Step Y — Accessibility: keyboard navigation through the flow

Without using a mouse, navigate through the entire import flow using only the keyboard (Tab, Enter, Space, Escape).

Pass:

• Tab moves focus between the mode cards in the Options stage
• Enter/Space selects a mode card
• Enter triggers the extract button
• The Cancel button is reachable by Tab
• Escape dismisses the entire flow from any stage

Step Z — Final consistency check

Run the same form screenshot through all four modes back-to-back (create a new blank form before each run). Compare the four results:

Check	Exact Copy	Structure Only	Styles Only	Smart Import
Fields added to canvas	Yes	Yes	No	Yes
Styles updated	Yes	No	Yes	No
Field types upgraded	Best effort	Basic mapping	N/A	Yes (AI inference)
Options on selects preserved	Yes	Yes	N/A	Yes
Canvas cleared before applying	Verify	Verify	Unchanged	Verify

Confirm each row of this table matches the actual behaviour in your build. Any deviation from the expected behaviour in the “Styles updated” or “Fields added” rows is a bug worth filing.

Quick Regression Checklist for Screenshot Import PRs

• ☐ Upload via button, paste, drag-drop, and URL all trigger the Options stage
• ☐ All four mode cards are visible and selectable
• ☐ Exact Copy applies styles AND fields
• ☐ Structure Only applies fields only — no style overwrite
• ☐ Copy Styles Only updates styles — no field change on existing canvas
• ☐ Smart Import upgrades field types intelligently (text → email/tel/date)
• ☐ Non-form images show “No form detected” — no fields added
• ☐ Cancel at any stage leaves the canvas unchanged
• ☐ Network error during extraction shows a recoverable error message
• ☐ Progress bar moves and completes — does not get stuck
• ☐ Undo reverts the import completely
• ☐ Imported styles persist after form save and reload
• ☐ No JavaScript console errors during the full flow (F12 → Console)
• ☐ Mobile viewport (375px): all interactive elements are reachable

When reporting a screenshot import bug, include the image used (or a description if it contains sensitive data), the extraction mode selected, the full API response from the /ai/extract-form-image endpoint (visible in F12 → Network), and the actual vs expected canvas output.