企业官网建设流程全解析

深入contact-congress：10种表单操作步骤（visit/fill_in/select/click_on）全解析

【免费下载链接】contact-congressSending electronic written messages to members of Congress by reverse engineering their contact forms.项目地址: https://gitcode.com/gh_mirrors/co/contact-congress

contact-congress 是一个通过逆向工程美国国会议员联系表单、实现向议员自动发送电子邮件的开源数据项目。它用 YAML 格式定义了一套标准化"表单操作步骤"，包括 visit、fill_in、select、click_on 等 10 种指令，任何机构或开发者都能基于这套数据批量向国会议员提交意见。本文将以新手友好的方式，逐一拆解这 10 种表单操作步骤的写法与使用场景，并附上项目中的真实示例，帮你快速上手这套自动化表单方案。

为什么需要一套统一的表单操作步骤

国会议员没有公开的电子邮箱，普通公民只能访问其官网的联系表单逐项填写。而每个议员的表单字段、下拉选项、验证码甚至多步流程都各不相同，靠人工维护成本极高。contact-congress 的做法是：把"如何成功填完一份表单"翻译成一份份 YAML 文件，用统一的"表单操作步骤"描述访问哪个页面、填哪些字段、点哪个按钮。完整规则定义在 documentation/schema.md，每份文件存放在 members/ 目录，以议员的 Bioguide ID 命名，例如 A000055.yaml。

表单操作步骤总览：10 种指令一览表

第 1 种步骤：visit —— 打开目标表单页面

visit 是所有流程的起点，值就是表单所在的 URL 字符串。以 A000055.yaml 为例，第一行步骤就是访问议员官网的联系页：

- visit: "https://aderholt.house.gov/contact-robert"

在完整表单中，method 和 action 分别定义了提交方式和提交地址（通常是 POST），而 visit 负责把浏览器带到表单所在页面，为后续操作做准备。

第 2 种步骤：find —— 等待页面元素加载完成

很多表单是多步流程，第二页的内容依赖上一页提交结果。find 的作用就是"等待某个 CSS 选择器对应的元素出现且可见"，元素未出现前不执行后续步骤，避免因页面未加载完而操作失败。它还可以通过 options 设置最长等待秒数，例如：

- find: - selector: "#required-first"

这表示页面出现 id 为 required-first 的输入框后，才继续填写信息。多步骤表单中，find 是衔接前后两页的关键"表单操作步骤"。

第 3 种步骤：fill_in —— 填写文本字段

fill_in 是最常用的输入指令，可以一次批量填写多个字段。每个字段通过 name、selector 定位，用 value 指定填入的内容，required 标记是否必填。注意：value 里不直接写用户真实数据，而是用$开头的变量占位符，如$NAME_FIRST、$EMAIL、$ADDRESS_STREET、$MESSAGE。这些占位符统一定义在 support/variables.yaml，方便客户端按需替换。真实写法见 A000055.yaml：

- fill_in: - name: required-first selector: "#required-first" value: $NAME_FIRST required: true - name: email selector: "#email" value: $EMAIL required: true

遇到 CAPTCHA 验证码时，也通过 fill_in 处理：把 value 设为$CAPTCHA_SOLUTION，并额外提供 captcha_selector 供求解器获取验证码图片。

第 4 种步骤：select —— 下拉框选择

select 用于处理下拉列表，写法与 fill_in 类似，但多了 options 字段列出所有可选值。如果选项的 value 是 AGR、BUD 这类缩写，不便于人读，可以用"显示文本: value"的哈希形式映射。例如 A000055.yaml 中议题选择：

- select: - name: required-issue selector: "#required-issue" value: $TOPIC options: Agriculture: AGR Budget: BUD Health: HEA Taxes: TAX

对于 50 个州这类各表单通用的选项，项目还提供了常量复用机制，定义在 support/constants.yaml，例如US_STATES、US_STATES_AND_TERRITORIES，避免每个文件重复维护一长串州名。

第 5-7 种步骤：check / uncheck / choose —— 复选框与单选按钮

这三种步骤用于处理勾选类控件：

• check：勾选复选框；
• uncheck：取消勾选复选框；
• choose：在一组单选按钮中选中某一个。

它们的字段属性和 fill_in 基本一致，区别在于 value 描述的是 checkbox 或 radio 自身的 value 属性，用于区分同名控件。你可以搜索 members/ 目录中带- check:或- choose:的文件找到大量实例，例如 A000367.yaml 就演示了单选按钮的用法，复选框只是把choose换成check。

第 8 种步骤：click_on —— 点击按钮提交表单

click_on 是流程的"终结者"，它提交表单，通常紧跟在一串输入步骤之后。点击目标通过 selector 定位，value 可选，用于补充按钮的 HTML value 属性以消除歧义。模板见 support/template.yaml：

- click_on: - selector: "#block-system-main form.bootstrap button.btn.btn-success"

点击提交后，如何判断是否成功？由顶层 success 字段定义：检查响应状态码是否为 200，以及页面 body 是否包含指定文本，例如 "your message has been sent"。

第 9 种步骤：wait —— 等待固定时间

wait 是实验性指令，表示在继续下一步前先等待指定的整数秒数，主要服务于需要 JS 渲染的页面。注意区分：wait 步骤是"固定等待 N 秒"，而 find 的 options 里的 wait 是"最多等待元素 N 秒出现"，两者用途不同。

第 10 种步骤：javascript —— 执行页面脚本

极少数页面必须通过脚本才能继续，此时可以使用 javascript 步骤执行自定义 JS。项目建议尽量模拟真实用户操作，仅在常规步骤无法推进时使用。比如 A000055.yaml 就有一段脚本，在提交前清除留言内容里的双引号：

- javascript: - value: document.querySelector("#required-message").value = document.querySelector("#required-message").value.replace(/"/g, '');

一张完整的表单操作步骤示例

把以上步骤串起来，就是一份完整议员的联系表单 YAML。下面这个来自 A000055.yaml 的真实流程：先访问页面 → 填写邮编 → 点击下一步 → 等待第二页字段 → 批量填写个人信息 → 选择称谓和议题 → 执行脚本清理文本 → 处理 ReCAPTCHA → 点击提交：

contact_form: method: POST steps: - visit: "https://aderholt.house.gov/contact-robert" - fill_in: - name: required-zip5 selector: "#required-zip5" value: $ADDRESS_ZIP5 - click_on: - value: "Go To Next Step" selector: "#emailForm #submit" - find: - selector: "#required-first" - fill_in: - name: required-first selector: "#required-first" value: $NAME_FIRST - select: - name: required-prefix selector: "#required-prefix" value: $NAME_PREFIX options: - Mr. - Ms. - Mrs. - recaptcha: - value: true - click_on: - selector: "#block-system-main form.bootstrap button.btn.btn-success"

新手快速入门：从模板开始写自己的步骤

想为某位议员编写表单操作步骤，最简单的方式是复制 support/template.yaml，它已经预留了 visit、fill_in、select、check、click_on 的完整骨架，你只需要对照议员的真实表单填写 name 和 selector，并把用户数据替换成 support/variables.yaml 中定义的变量即可。完成后按[bioguide].yaml命名放入 members/ 目录并提交 PR，就能为开源社区贡献一份可自动填写的表单数据。

常见问题解答

Q1：这些步骤由什么框架执行？这套 YAML 结构借鉴了 Ruby 测试框架 Capybara 的方法命名，但不依赖它。任何能解析 YAML 的客户端（如无头浏览器、直接 POST 的脚本）都可以按步骤执行，schema 文档对此有详细说明。

Q2：所有议员的表单都能覆盖吗？项目已收录了几乎所有参议院和众议院议员的表单文件，参议院列表可直接在 README.md 的 Current Forms 表格中按 Bioguide ID 查阅。

Q3：验证码怎么处理？普通验证码用$CAPTCHA_SOLUTION变量交给外部求解器；Google ReCAPTCHA 则用专门的recaptcha指令在提交前标记，由管理员在提交后离线验证。

总结

contact-congress 用 10 种简洁的表单操作步骤，把"给议员发邮件"这件繁琐的事变成了一份份可维护、可复用的 YAML 数据。无论你是想参与开源贡献、构建公民参政工具，还是单纯研究表单自动化，从理解 visit、fill_in、select、click_on 这 4 个最核心的步骤入手，再逐步掌握 find、check、choose、wait、javascript 等进阶指令，就能快速读懂项目中的每一份表单文件，甚至写出自己的第一份 YAML。

【免费下载链接】contact-congressSending electronic written messages to members of Congress by reverse engineering their contact forms.项目地址: https://gitcode.com/gh_mirrors/co/contact-congress