GForm

Appearance

Roadmap ​

Public reliability plan for gform. Modest, grounded, and separate from what already ships.

Shipped behavior: limitations · file uploads · artifacts

Issue-ready briefs for maintainers live in the repository under maintainer/planning/ (not published on this site).

This page describes planned work. Nothing here is a promise that Google’s UI will always cooperate.

Phase 1 — Reproducible pressure harness ​

Goal: Make concurrency and picker failures repeatable before changing implementation.

Planned:

  • Controlled test forms owned by maintainers
  • Fixtures: anonymous, authenticated, file-upload, mixed-question
  • Concurrency from 1 through the documented maximum (16)
  • local / gdrive / remote content sources
  • Linux Chrome, Playwright Chromium, and supported WSL paths
  • Artifacts for every failing worker
  • Classify failures by stage and reason
  • Capture success rate, duration, retries, throttling indicators
  • Never target third-party forms

Acceptance direction: documented pressure-test command or maintainer script; reproducible artifact bundles; stable reason-code classification; no unbounded public-form load testing.

Phase 2 — Harden file-picker and upload execution ​

Goal: Reduce flaky failures caused by Google’s file UI.

Investigate and, where safe, implement:

  • Stronger readiness checks before opening the picker
  • Scoped detection of newly created file inputs
  • Per-worker picker/input isolation
  • Stale element detection
  • Bounded retries with jitter
  • Verify the selected file is attached before proceeding
  • Distinguish retryable picker failures from headed-assist requirements
  • Cleanup of picker dialogs and stale DOM state
  • Explicit timeout stages
  • Richer screenshots and trace annotations
  • Guard against workers attaching to the wrong input
  • Content-cache concurrency safety

No uncontrolled retries. Every retry must be bounded, observable, and represented in artifacts.

Phase 3 — Full supported concurrency consistently green ​

Goal: Demonstrate reliable execution at the documented worker maximum under controlled test conditions.

Focus:

  • Authenticated worker isolation and browser context isolation
  • Auth storage safety
  • Google Drive source cache safety
  • Race detection and worker lifecycle cleanup
  • Abort propagation and continue-on-error
  • Batch rollups and accurate child statuses
  • Deterministic pool / variant allocation
  • No cross-worker file or answer leakage
  • No orphaned browsers after failure or cancellation

“Green” means (example matrix): repeated controlled runs; zero internal race-condition failures; complete child artifacts; workers cleaned up; external throttling reported separately from internal defects.

This does not mean all external Google UI runs always succeed.

Phase 4 — Smarter batch terminal output ​

Goal: Useful live visibility without flooding the terminal with identical messages.

Two layers (required):

  1. Human live view — concise, grouped, progress-oriented; errors immediate; repeated notices summarized
  2. Complete diagnostic record — full event stream in artifacts / debug; timestamps; worker identity; ordering preserved

Design constraints:

  • Do not discard diagnostics to silence the TTY
  • Do not change JSON output semantics via aggregation
  • Do not merge different errors just because text looks similar
  • Prefer structured event keys over fragile string-only dedupe
  • Support --debug expansion and --no-live print-and-go
  • Flush aggregated messages before exit; avoid redraw corruption

Illustrative (not a committed format — logger architecture decides):

text
[notice] browser · headless · Playwright Chromium ×5 workers
[notice] content · drive cache hit · report.pptx ×5
[progress] <form> · 12/20 · ✓10 ✗1 ⊘1 · 5 workers

Phase 5 — Reliability contracts and regression gates ​

Goal: Prevent concurrency, picker, logging, and artifact regressions.

Planned:

  • Unit tests for aggregation and reason codes
  • Integration tests for worker isolation and cancellation
  • Retry-bound and artifact-completeness tests
  • Snapshot tests for concise terminal output where appropriate
  • JSON output contract tests
  • Pressure tests (manual or controlled CI) on owned forms only
  • Documentation and broken-link checks
  • Command-example validation where practical

Normal CI stays separate from tests that need live Google Forms or real sessions.

Issue-ready themes ​

Tracked as planning briefs in the repo (maintainer/planning/) — create GitHub issues when ready:

  1. Concurrent Google file-picker isolation
  2. Bounded retry strategy for retryable upload UI failures
  3. Controlled full-concurrency pressure harness
  4. Batch log aggregation and duplicate suppression
  5. Worker cleanup and cancellation reliability
  6. Artifact completeness under partial batch failure
  7. Concurrency-safe Google Drive content cache
  8. Public reliability and limitation documentation (this page + limitations)