Overview
Separate transport from parsing so ordinary development is deterministic and credential-free. The live lane is opt-in, target-allowlisted, budgeted, and incapable of silently replacing fixtures.
Prerequisites
- A repository-owned Bright Data adapter boundary
- Synthetic or approved redacted fixtures with expected schemas
- A test runner and a protected live-test environment
Instructions
Step 1: Map the boundary
Read the adapter and Grep for direct proxy/API calls in business logic. Move transport behind a narrow interface before recording fixtures.
Step 2: Create explicit modes
Write configuration with fixture as the default and live requiring three independent gates.
brightdata:
mode: fixture
live_requires:
- BRIGHTDATA_LIVE_TEST=1
- approved_target_manifest
- bounded_cost_budget
Step 3: Test contract behavior
Add fixtures for success, 407, policy 403, 429, building, ready, failed, empty, and expired states. Test parsers against provider fields rather than copied HTML.
Step 4: Run the loop
Use Bash(npm:*) for unit and contract tests. Permit the live suite only in a protected environment, against an approved target, with a one-job ceiling and redacted receipt.
Tool Discipline
Use Read and Grep for discovery. Use Write and Edit only for the adapter, fixtures, tests, and documented configuration. Use Bash(npm:*) for the named local suites; never let a default test command send live Bright Data traffic.
Output
- A fixture-first transport adapter
- Deterministic success and failure fixtures
- A separately gated live-test receipt and explicit budget
Examples
A parser change should pass against a synthetic snapshot and recorded provider-error metadata with no credentials present. A maintainer may later enable one protected live job; its output updates no fixture automatically and is reviewed before adoption.
Error Handling
| Failure | Meaning | Response |
|---|---|---|
| Unit tests attempt network access | Transport leaked into parsing code | Block network and refactor through the adapter |
| Fixture contains target data | Captured live content was committed | Remove it and replace it with synthetic minimal data |
| Live gate has only one switch | Accidental execution remains possible | Require environment, target manifest, and budget gates |