···11+# atproto-smoke
22+33+This directory is the extraction staging area for a standalone `bsky.app`
44+compatibility smoke suite that can be used by multiple PDS implementations, not
55+just `perlsky`. The browser runtime now lives here, while the old
66+`tools/browser-automation/*` paths remain as thin compatibility wrappers for
77+the current `perlsky` workflow.
88+99+## Quickstart
1010+1111+```sh
1212+npm install
1313+npx playwright install chromium
1414+node bin/atproto-smoke.mjs print-example --mode dual > config.json
1515+$EDITOR config.json
1616+node bin/atproto-smoke.mjs run-dual --config config.json
1717+```
1818+1919+For the lowest-friction path, point the suite at an existing PDS and two
2020+existing accounts. The package is intentionally adapter-friendly, but
2121+bring-your-own accounts are the default path for non-Perl PDS implementations.
2222+2323+## Current Scope
2424+2525+The existing browser automation is already strong enough to be useful outside
2626+this repo:
2727+2828+- reusable-account `bsky.app` smoke flows
2929+- post, image post, like, repost, quote, reply, bookmark, follow
3030+- list lifecycle
3131+- profile edit and avatar upload
3232+- notifications checks
3333+- settings-depth flows
3434+- strict artifacts with screenshots, console output, failed requests, failed
3535+ HTTP responses, and recent XRPC traffic
3636+3737+DMs are intentionally deferred for now. The current suite is focused on stable
3838+social, list, and settings interactions first.
3939+4040+## Extraction Shape
4141+4242+The target standalone project shape is:
4343+4444+1. Generic core browser flows and artifact handling
4545+2. A bring-your-own-accounts mode with minimal configuration
4646+3. Thin per-PDS adapters for provisioning and implementation-specific defaults
4747+4848+The generic runtime, config builders, and adapter helpers now live here. The
4949+older `tools/browser-automation/` entrypoints simply forward into this package
5050+so the existing repo scripts keep working during the extraction.
5151+5252+## Current CLI
5353+5454+The package now has its own CLI entrypoint:
5555+5656+```sh
5757+node atproto-smoke/bin/atproto-smoke.mjs print-example --mode dual
5858+node atproto-smoke/bin/atproto-smoke.mjs validate --mode dual --config atproto-smoke/examples/bring-your-own-dual.json
5959+node atproto-smoke/bin/atproto-smoke.mjs run-dual --config atproto-smoke/examples/bring-your-own-dual.json
6060+```
6161+6262+Examples live in [examples/](./examples):
6363+6464+- `bring-your-own-single.json`
6565+- `bring-your-own-dual.json`
6666+- `perlsky-dual.json`
6767+6868+## Minimal Configuration Goal
6969+7070+The default experience for other PDS developers should be:
7171+7272+- provide a `pdsUrl`
7373+- provide one or two existing account credentials
7474+- optionally provide a `targetHandle`
7575+- run the suite against `bsky.app`
7676+7777+Provisioning is intentionally adapter-specific. That means `perlsky` can keep a
7878+helpful invite/bootstrap path, while other PDSes like `rsky` or `pegasus` can
7979+add their own adapters without changing the core browser flows.
8080+8181+## Current Adapter Contract
8282+8383+The staging helpers in `src/` model two layers:
8484+8585+- `adapters/bring-your-own.mjs`
8686+ For the lowest-friction mode where callers supply existing credentials
8787+- `adapters/perlsky.mjs`
8888+ For `perlsky`-specific defaults like cleanup prefixes and adapter tagging
8989+9090+The current config contract is intentionally small:
9191+9292+- suite-level settings:
9393+ `pdsUrl`, `artifactsDir`, `appUrl`, `publicApiUrl`, `targetHandle`,
9494+ `publicCheckTimeoutMs`, `headless`, `strictErrors`, `publicChecks`,
9595+ `browserExecutablePath`, `adapter`
9696+- account-level settings:
9797+ `handle`, `password`, `birthdate`, `postText`, `mediaPostText`, `quoteText`,
9898+ `replyText`, `profileNote`, `cleanupPostPrefixes`
9999+100100+`pdsHost` is derived automatically from `pdsUrl`, so callers do not need any
101101+perlsky-specific host-setting knowledge just to point the browser at a custom
102102+PDS.
103103+104104+## V2 Ideas
105105+106106+The long-term direction is a test pyramid, not a browser-only harness and not a
107107+pure endpoint-only harness:
108108+109109+1. direct PDS/AppView contract tests
110110+2. cross-service integration checks
111111+3. a thinner `bsky.app` smoke on top
112112+113113+The browser layer stays because it catches real `social-app` assumptions and
114114+AppView proxying issues. The direct API/AppView layers belong underneath it so
115115+regressions become easier to debug and less brittle when the UI changes.
116116+117117+In other words: this project should eventually answer both "does my PDS return
118118+the right protocol shapes?" and "does it still behave correctly through
119119+`bsky.app` and AppView-backed reads?".
120120+121121+## Planned Next Steps
122122+123123+- keep `script/perlsky-browser-smoke` as a thin `perlsky` adapter over this
124124+ generic package
125125+- add a repo-independent install story once the extracted package boundary
126126+ settles
127127+- add direct API/AppView contract tests as the first major v2 expansion
128128+- revisit a JS-to-TS migration later, after the standalone package boundary is
129129+ stable
···11+export * from './config.mjs';
22+export * from './adapters/bring-your-own.mjs';
33+export * from './adapters/perlsky.mjs';
44+export * from './browser/run-single.mjs';
55+export * from './browser/run-dual.mjs';
66+export * from './cli.mjs';