Generate synthetic Google Forms responses, reuse complete answer profiles, and fill forms from your terminal.
Supports public forms that accept anonymous responses. Google-account sign-in and file-upload questions are not supported.
python -m pip install "git+https://github.com/yogeshkrishna/google_form_test_bot.git"
gformbotThis checkout is 0.4.0.dev0, an unpublished development build. The commands and features below describe GitHub master. python -m pip install gformbot installs the older published release instead.
Requires Python 3.10 or newer and an installed Chrome, Firefox, or Edge browser for generation and filling. Selenium manages the driver. Use python -m gformbot if the command is not on your PATH.
Windows x64 wheels include a private Selenium subset with the original Windows driver manager. Other platforms use official Selenium. Existing Selenium installations can coexist; pip does not remove old shared dependencies during an upgrade. Build details and measurements.
The wizard's file picker opens after you press Enter. It needs a graphical desktop and Python's Tk support (python3-tk on Linux). Commands accept paths directly.
generate fills and submits automatically. Use prepare to save answers without filling a form, or add --halt to keep filled tabs open and click Submit yourself. The no-argument wizard asks which action to take.
| Command | Behavior |
|---|---|
gformbot |
Guided setup, answer sources, saved work, review, and execution choices. |
gformbot generate URL |
Prepare answers, fill the form, and submit. --halt stops before submission and keeps the filled tabs open. |
gformbot prepare URL |
Prepare and save response JSON without filling or submitting a form. AI preparation can still open ChatGPT. |
gformbot preview [FILE.json] |
Open a JSON file in your system's default app. Without a file, choose unfinished saved responses or saved AI work, newest first. This command does not fill or submit. |
Public respondent URLs and forms.gle short links work. The wizard displays sections, instructions, descriptions, questions, choices, required fields, and supported constraints before preparing answers.
Account-restricted forms, verified-account email collection and one-response-per-account forms stop before preparation or filling. Complete those forms manually or ask their owner for an anonymous test copy. Ordinary typed-email questions remain supported.
# Prepare answers for later.
gformbot prepare "FORM_URL" -n 10 -m "Varied fictional student profiles"
# View saved JSON in your default app.
gformbot preview
gformbot preview "gformbot-responses.json"
# Reuse supplied rows and review filled tabs yourself.
gformbot generate "FORM_URL" --data "responses.csv" -n 5 --halt
# Use saved JSON, including resumable saved work.
gformbot generate "FORM_URL" --data "gformbot-responses.json" --halt
# Generate from reference patterns, then fill and submit.
gformbot generate "FORM_URL" -n 10 --like "reference.csv" -m "Include varied age groups"Both generate and prepare accept -n for the response count, -m / --message for instructions, --like for a reference CSV, --data for supplied CSV or saved gformbot JSON, and --browser for browser selection. --halt belongs to generate. Without -n, the tool uses a matching saved form configuration's count, or one response when none matches. Saved JSON carries its own response data and progress. Output filenames are chosen automatically.
Use --data to execute supplied answers and --like to guide newly generated answers. Reference patterns and instructions guide generation; they do not establish statistical fidelity or semantic consistency.
The wizard offers AI generation, your own data, or random choice answers. AI generation can create fresh fictional profiles, follow a reference CSV, or add profiles based on existing responses. CSV import keeps complete rows together, with ordered, shuffled, or sampling-with-repetition choices.
Random mode supports multiple choice, checkboxes, dropdowns, and numeric scales. Automatic reference sampling keeps whole choice profiles together. Manual option weights are relative chances, not exact quotas. AI can complete written/date answers; optional unanswered fields can stay blank.
Review the prepared answers, view a response, edit a copy, export CSV, save for later, test filling without submission, or explicitly choose submission. Quiet review opens no browser until you select a response. Already open responses keep your edits; restarting fills the saved prepared answers.
Response JSON stores prepared answers and execution progress. The wizard also lists saved AI progress and can resume accepted work after an interruption. Supplied JSON can be used through --data. preview opens these files for viewing; use the wizard or generate --data to continue work.
A local submission journal records attempts and confirmations. Confirmed rows are skipped when work resumes. An uncertain outcome requires checking the form's responses before deciding whether to retry. Copied plans share their identity on the same machine; duplicate protection depends on retaining the local journal.
Imported CSV/JSON files are never deleted. Files saved by prepare remain available. Temporary response JSON owned by the tool is removed only after every response is confirmed in the submission journal; unfinished or uncertain work stays saved. Older files with missing retention settings or ambiguous ownership (including legacy command output) stay saved. Using a saved file as --data preserves that input.
Run logs record prepared answers and outcomes. Manual changes in a browser can differ from the prepared values.
Form directions and link destinations are saved from the introduction, visited sections, question descriptions, and the confirmed completion screen. A short Next steps summary shows links and custom completion messages once. Read everything later with gformbot log --followups, or gformbot log "custom-runs.csv" --followups for a custom log. --last limits the number of responses shown. These notes stay in the local journal after temporary response files are cleaned up.
Completion messages are captured only when the browser confirms submission, including manual review and --halt. Filling alone or manually reconciling an uncertain result does not create a completion observation. The tool never follows these links or performs outside actions. Public group invites are preserved; embedded URL credentials, account/edit-response links and known secret URL parameters are excluded or redacted. Redacted links may not work. Ordinary instruction text is retained without automatic secret detection.
AI generation uses ChatGPT in a visible private browser, with no model download, local server, or API key. Website limits apply; you may need to sign in or complete verification yourself. Browser setup is checked before generation.
The form context, instructions, reference frequencies, and up to six complete reference examples are sent to ChatGPT. Returned profiles are checked against supported formats, choices, and constraints. These checks do not prove that generated answers are meaningful, representative, or accurate. Failed generation preserves accepted work instead of substituting random answers.
Outgoing requests redact known secret URL parameters and omit embedded credentials, account links and edit-response links. Public invitation links remain available. This does not detect private information written as ordinary text. Original form metadata, supplied answers and AI checkpoints remain unchanged in local plaintext files; keep them private.
CSV columns map through question titles, Q1 / Q2 headers, or entry.ID identifiers. Review ambiguous or unmatched mappings in the wizard. Blank optional answers stay blank; missing required answers must be resolved. Reference CSVs also need complete valid profiles.
Single-choice values use exact option labels. Checkbox JSON arrays preserve commas inside labels:
Q1,Q2
Student,"[""Roads, footpaths or crossings"", ""Bus stops""]"Short text occupies one line; paragraphs may contain newlines. Number comparisons/ranges, whole numbers, text contains/does-not-contain, character limits, email and checkbox constraints share the same checks across CSV import, AI output, editing, and execution. Number answers retain their original text. Character limits count UTF-16 units as Google's client does, so an emoji can count as two characters. Checkbox repairs are explicit and recorded.
Pattern validation supports verified JavaScript-compatible syntax and all four Forms pattern operations. Checks run in one lazy background process with bounded waits and caches; no regex dependency is installed. Unverified syntax (including backreferences, named groups, lookbehind, inline flags, and \S inside character classes) stops explicitly. Patterns are limited to 4,096 characters including operation wrappers, and answers to one million UTF-16 units for pattern checks. URL-format rules are checked locally; Google's own validation remains authoritative. Unknown validation families stop explicitly. A valid filled page is not proof of submission.
Dates use YYYY-MM-DD or YYYY-MM-DD HH:MM; yearless questions use MM-DD with optional time. Google Forms CSV dates are normalized without changing the source. For ambiguous dates, generate and prepare accept --date-order mdy or --date-order dmy; the wizard asks you to choose. An explicit option overrides matching saved settings. Impossible dates and nonzero seconds are rejected.
Clock time uses HH:MM (00:00–23:59); duration uses HH:MM:SS (hours 00–72, minutes/seconds 00–59). CSV clock values may include AM/PM or zero seconds; nonzero clock seconds are rejected rather than discarded. No timezone conversion is applied.
Icon ratings (stars, hearts and thumbs) retain their question type and use exact numeric strings such as "4"; required, optional, import/export and choice-weight behavior matches other single-choice questions.
For an actual Other selection, use {"choices": ["Python"], "other": "Rust"} (radio: empty choices). Other counts as one checkbox selection. CSV cells use the same JSON object; unknown labels are never silently interpreted as Other. Ordinary strings/lists remain unchanged. Plans requiring Other use format 2; older plans retain their identities and progress.
Media items and question/option attachments stay in form order. AI generation needs --media-context "description of the relevant visual information" or an explicit decorative declaration; the wizard asks once when needed. Theme images do not trigger this. Supplied-answer workflows need no AI media interpretation. No images/videos are downloaded or interpreted automatically.
Next, Submit and per-question clearing prefer verified Google control identities over English labels. Unknown or conflicting controls stop explicitly. This does not claim universal language support: unrecognized translated account-consent prompts still require manual handling.
File-upload questions are unsupported and never transfer files. Older plans containing prepared uploads cannot execute; their files and journal records are preserved. CSV/JSON import and export still work normally.
Supported questions include short text, paragraphs, multiple choice, checkboxes, dropdowns, numeric scales, icon ratings, explicit Other answers, dates with optional year/time, clock time, duration, and both grid types. Grid rows use their entry IDs or Google CSV headers (Question [Row]); required rows and one-response-per-column rules are checked together. Section routing follows each response's choices, including skipped sections and early Submit. Only reached questions require answers; repeated sections stop with an error. Instruction blocks and section descriptions are retained as text. Unsupported controls and validation block their sections. A response can avoid those sections only when its complete route is understood; unclear routing and legacy unscoped compatibility findings still block the form. Generated routes respect fixed choices and positive weights while avoiding unsupported sections and loops. Closed or restricted forms retain unfinished work.
gformbot config --show
gformbot config --edit
gformbot log --last 20
gformbot log --followups
gformbot doctor
gformbot doctor --check
gformbot --help
gformbot --versiondoctor --check exits unsuccessfully when a required local prerequisite is missing. Runtime errors go to stderr. Set GFORMBOT_DEBUG=1 to retain a traceback when diagnosing a failure; avoid sharing logs containing private responses.
python -m pip install -e ".[dev]"
python -m ruff check .
python -m pytest
python -m build
python -m twine check dist/*Set GFORMBOT_BROWSER_TESTS=1 for local Chrome fixtures. These exercise a local test server without Google submissions or live AI. Firefox and Edge need their own environment checks.
Set GFORMBOT_TEST_BROWSER=edge or firefox to run the same fixtures against that installed browser.
CI checks Windows/Ubuntu on Python 3.10, 3.12, 3.13, and 3.14, builds both wheel variants, smoke-tests them outside the checkout, and runs Chrome fixtures on Ubuntu plus Chrome/Edge/Firefox fixtures on Windows. It uploads build artifacts without publishing packages or creating releases.