this repo has no description
Tighten README: cut redundancy, collapse planning sections
Consolidate the three overlapping quickstart/CLI sections into one,
replace internal roadmap sections with a two-sentence future direction,
and make the opening line actually describe what the tool does.
+35
-145
+35
-145
README.md
+35
-145
README.md
···
1
1
# atproto-smoke
2
2
3
-
`atproto-smoke` is a standalone `bsky.app` compatibility smoke suite for AT
4
-
Protocol PDS implementations. It is intended to be useful across multiple PDS
5
-
projects, not just `perlsky`.
3
+
Browser-driven smoke tests for any AT Protocol PDS. Point it at your server, give it two accounts, and it will log into `bsky.app` and exercise the real social flows — posting, following, lists, notifications, settings, and more.
6
4
7
-
Today the suite focuses on real browser-driven interoperability through
8
-
`bsky.app`, AppView-backed reads, and a reusable-account workflow that avoids
9
-
minting fresh smoke actors on every run.
5
+
It grew out of [perlsky](https://github.com/aliceisjustplaying/perlsky) but is designed to work with any PDS implementation.
10
6
11
-
## Quickstart
7
+
## Quick start
12
8
13
9
```sh
14
10
npm install
15
11
npx playwright install chromium
16
-
node bin/atproto-smoke.mjs list-adapters
12
+
13
+
# generate a config, fill in your PDS URL and credentials
17
14
node bin/atproto-smoke.mjs write-example --mode dual --output config.json
18
15
$EDITOR config.json
19
-
node bin/atproto-smoke.mjs run-dual --config config.json
20
-
```
21
16
22
-
For the lowest-friction path, point the suite at an existing PDS and two
23
-
existing accounts. The package is intentionally adapter-friendly, but
24
-
bring-your-own accounts are the default path for non-Perl PDS implementations.
25
-
26
-
Five-minute path for a non-Perl PDS:
27
-
28
-
1. Clone `atproto-smoke`.
29
-
2. Run `npm install`.
30
-
3. Run `npx playwright install chromium`.
31
-
4. Write a config with `write-example --mode dual --output config.json`.
32
-
5. Replace the example `pdsUrl`, handles, and passwords with real credentials.
33
-
6. Run `node bin/atproto-smoke.mjs validate --mode dual --config config.json`.
34
-
7. Run `node bin/atproto-smoke.mjs run-dual --config config.json`.
35
-
36
-
## Using From perlsky
37
-
38
-
`perlsky` consumes this suite as an external checkout.
39
-
40
-
`perlsky` lives here:
41
-
42
-
- https://github.com/aliceisjustplaying/perlsky
43
-
- https://tangled.org/alice.mosphere.at/perlsky
44
-
45
-
If you keep the repos side by side like this:
46
-
47
-
```text
48
-
.../perlsky
49
-
.../atproto-smoke
17
+
# validate and run
18
+
node bin/atproto-smoke.mjs validate --mode dual --config config.json
19
+
node bin/atproto-smoke.mjs run-dual --config config.json
50
20
```
51
21
52
-
then `script/perlsky-browser-smoke` will find `atproto-smoke` automatically.
53
-
Otherwise set `PERLSKY_BROWSER_SUITE_ROOT=/path/to/atproto-smoke`.
22
+
That's it. Provide a `pdsUrl` and two account credentials, and the suite handles the rest. Run commands print per-step progress to `stderr` and write a JSON summary to `stdout` (`--json-only` for machine-readable output only).
54
23
55
-
## Current Scope
24
+
## What it covers
56
25
57
-
The existing browser automation is already strong enough to be useful outside
58
-
this repo:
26
+
- Post creation (text and image), like, repost, quote, reply, bookmark, follow/unfollow
27
+
- Profile edit and avatar upload
28
+
- List lifecycle (create, edit, add/remove members, delete)
29
+
- Notification checks
30
+
- Settings-depth flows
31
+
- Signed-in profile reload with follow/follower count assertions
32
+
- Mute/unmute, block/unblock, report draft
59
33
60
-
- reusable-account `bsky.app` smoke flows
61
-
- post, image post, like, repost, quote, reply, bookmark, follow
62
-
- list lifecycle
63
-
- profile edit and avatar upload
64
-
- notifications checks
65
-
- settings-depth flows
66
-
- strict artifacts with screenshots, console output, failed requests, failed
67
-
HTTP responses, and recent XRPC traffic
68
-
- bounded per-step timeouts so late browser stalls fail with artifacts instead
69
-
of hanging forever
34
+
Every run produces screenshots, console output, failed requests, HTTP failures, and recent XRPC traffic as artifacts. Steps have bounded timeouts so a hung browser fails with artifacts instead of hanging forever.
70
35
71
-
DMs are intentionally deferred for now. The current suite is focused on stable
72
-
social, list, and settings interactions first.
36
+
DMs are intentionally deferred — the current suite is focused on stable social, list, and settings interactions first.
73
37
74
-
## Built-in Adapters
38
+
## Adapters
75
39
76
-
List them at any time with:
40
+
The suite ships with built-in adapters for different PDS implementations:
77
41
78
42
```sh
79
43
node bin/atproto-smoke.mjs list-adapters
80
44
```
81
45
82
-
Current built-ins:
83
-
84
-
- `bring-your-own`
85
-
The default, lowest-friction mode for any PDS that already has one or two
86
-
accounts you can log into.
87
-
- `perlsky`
88
-
A thin adapter for `perlsky` defaults such as cleanup prefixes. The account
89
-
bootstrap and reusable-pair workflow still live in `perlsky` itself.
90
-
91
-
The adapter boundary is documented in [docs/ADAPTERS.md](./docs/ADAPTERS.md).
92
-
Representative CLI and `summary.json` examples live in
93
-
[docs/SAMPLE_OUTPUT.md](./docs/SAMPLE_OUTPUT.md).
46
+
- **`bring-your-own`** — the default. Works with any PDS that has accounts you can log into.
47
+
- **`perlsky`** — thin adapter for `perlsky`-specific defaults like cleanup prefixes.
94
48
95
-
## Extraction Shape
49
+
Other PDS projects (rsky, pegasus, etc.) can add their own adapters without changing the core browser flows. The adapter contract is documented in [docs/ADAPTERS.md](./docs/ADAPTERS.md).
96
50
97
-
The target standalone project shape is:
51
+
## Using from perlsky
98
52
99
-
1. Generic core browser flows and artifact handling
100
-
2. A bring-your-own-accounts mode with minimal configuration
101
-
3. Thin per-PDS adapters for provisioning and implementation-specific defaults
53
+
If you keep the repos side by side, `perlsky` finds this checkout automatically:
102
54
103
-
The generic runtime, config builders, and adapter helpers live here. `perlsky`
104
-
keeps thin wrapper entrypoints so its existing local workflow still works while
105
-
the suite itself evolves independently.
106
-
107
-
## Current CLI
108
-
109
-
The package now has its own CLI entrypoint:
110
-
111
-
```sh
112
-
node atproto-smoke/bin/atproto-smoke.mjs print-example --mode dual
113
-
node atproto-smoke/bin/atproto-smoke.mjs write-example --mode dual --output config.json
114
-
node atproto-smoke/bin/atproto-smoke.mjs list-adapters
115
-
node atproto-smoke/bin/atproto-smoke.mjs validate --mode dual --config atproto-smoke/examples/bring-your-own-dual.json
116
-
node atproto-smoke/bin/atproto-smoke.mjs run-dual --config atproto-smoke/examples/bring-your-own-dual.json
55
+
```text
56
+
.../perlsky
57
+
.../atproto-smoke
117
58
```
118
59
119
-
Examples live in [examples/](./examples):
120
-
121
-
- `bring-your-own-single.json`
122
-
- `bring-your-own-dual.json`
123
-
- `perlsky-dual.json`
124
-
125
-
## Minimal Configuration Goal
126
-
127
-
The default experience for other PDS developers should be:
128
-
129
-
- provide a `pdsUrl`
130
-
- provide one or two existing account credentials
131
-
- optionally provide a `targetHandle`
132
-
- run the suite against `bsky.app`
133
-
134
-
Provisioning is intentionally adapter-specific. That means `perlsky` can keep a
135
-
helpful invite/bootstrap path, while other PDSes like `rsky` or `pegasus` can
136
-
add their own adapters without changing the core browser flows.
60
+
Otherwise set `PERLSKY_BROWSER_SUITE_ROOT=/path/to/atproto-smoke`.
137
61
138
-
## Config Surface
62
+
## Config
139
63
140
-
The current config contract is intentionally small:
64
+
The config surface is intentionally small — suite-level settings (`pdsUrl`, `artifactsDir`, `headless`, `strictErrors`, `targetHandle`, `remoteReplyPostUrl`, etc.) and per-account settings (`handle`, `password`, `postText`, `cleanupPostPrefixes`, etc.). `pdsHost` is derived from `pdsUrl` automatically.
141
65
142
-
- suite-level settings:
143
-
`pdsUrl`, `artifactsDir`, `appUrl`, `publicApiUrl`, `targetHandle`,
144
-
`publicCheckTimeoutMs`, `stepTimeoutMs`, `headless`, `strictErrors`,
145
-
`publicChecks`,
146
-
`browserExecutablePath`, `adapter`
147
-
- account-level settings:
148
-
`handle`, `password`, `birthdate`, `postText`, `mediaPostText`, `quoteText`,
149
-
`replyText`, `profileNote`, `cleanupPostPrefixes`
66
+
Example configs live in [examples/](./examples). See [docs/SAMPLE_OUTPUT.md](./docs/SAMPLE_OUTPUT.md) for representative CLI output and `summary.json` shape.
150
67
151
-
`pdsHost` is derived automatically from `pdsUrl`, so callers do not need any
152
-
perlsky-specific host-setting knowledge just to point the browser at a custom
153
-
PDS.
68
+
## Future direction
154
69
155
-
## V2 Ideas
156
-
157
-
The long-term direction is a test pyramid, not a browser-only harness and not a
158
-
pure endpoint-only harness:
159
-
160
-
1. direct PDS/AppView contract tests
161
-
2. cross-service integration checks
162
-
3. a thinner `bsky.app` smoke on top
163
-
164
-
The browser layer stays because it catches real `social-app` assumptions and
165
-
AppView proxying issues. The direct API/AppView layers belong underneath it so
166
-
regressions become easier to debug and less brittle when the UI changes.
167
-
168
-
In other words: this project should eventually answer both "does my PDS return
169
-
the right protocol shapes?" and "does it still behave correctly through
170
-
`bsky.app` and AppView-backed reads?".
171
-
172
-
## Planned Next Steps
173
-
174
-
- keep `script/perlsky-browser-smoke` as a thin `perlsky` adapter over this
175
-
package
176
-
- add a repo-independent install story once the extracted package boundary
177
-
settles
178
-
- add direct API/AppView contract tests as the first major v2 expansion
179
-
- revisit a JS-to-TS migration later, after the standalone package boundary is
180
-
stable
70
+
The long-term shape is a test pyramid: direct PDS/AppView contract tests at the bottom, cross-service integration checks in the middle, and a thinner `bsky.app` browser smoke on top. The browser layer stays because it catches real `social-app` assumptions that API tests miss.