docs: add development guide for Docker testing and screenshot recording

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

Author: pftg

README.md

@@ -666,6 +666,37 @@ You can also run `bin/console` for an interactive prompt that will allow you to
 
 To install this gem onto your local machine, run `bundle exec rake install`.
 
+### Running tests in Docker
+
+Screenshot tests depend on exact browser rendering, which varies across OS and browser versions. Use `bin/dtest` to run tests inside Docker for consistent, reproducible results matching CI:
+
+```bash
+bin/dtest                          # Run all tests with all drivers
+bin/dtest test/integration/        # Run specific test directory
+```
+
+This builds a Docker image with Chrome and runs the test suite against three Capybara drivers: `cuprite`, `selenium_chrome_headless`, and `selenium_headless`.
+
+#### Recording baseline screenshots
+
+Screenshot baselines are committed to the repo and compared against during tests. When you set up the project for the first time, or after upgrading the browser/driver, you need to re-record them:
+
+```bash
+RECORD_SCREENSHOTS=1 bin/dtest
+```
+
+This skips screenshot comparisons and saves new baselines instead. Without this step, tests will fail because your local browser renders pixels differently from the previously committed baselines.
+
+#### Experimental: Lightpanda browser
+
+[Lightpanda](https://github.com/lightpanda-io/browser) is included as an experimental CDP-based headless browser. It can be enabled for the `cuprite` driver:
+
+```bash
+ENABLE_LIGHTPANDA=1 bin/dtest
+```
+
+**Note:** Lightpanda's CDP support does not yet cover viewport resizing or full execution context management, so screenshot comparison tests may fail. This is gated behind the env var until Lightpanda matures.
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md)