Skip to content

bikeindex/bike_index / .claude/skills/sandbox-test-setup

sandbox-test-setup

Verified

Bike Index Ruby + RSpec environment setup for each place this repo runs: a local macOS Conductor workspace, a spawned `.claude/worktrees/…` git worktree, and Claude Code's Linux web sandbox — getting `ruby`, `bundle`, `bin/lint`, a database, seeds, a dev server and a browser working there. **Read it before the first command in a spawned worktree**, which starts with `bin/workspace_setup` (without it `bin/env` hands back the main checkout's port, database and Redis). Read it whenever a session runs RSpec, `bundle` or `bin/lint`, needs a dev server or seeded data, or hits: a missing `.workspace_id` or `node_modules`, a `$BASE_URL` serving another branch, `Could not find 'bundler' (4.0.x)`, `command not found: rspec`, `uninitialized constant Pathname` or `undefined method 'intersect?' for Array` from a `bin/` script, `Sprockets::Rails::Helper::AssetNotFound`, `tailwind.css is not present`, `LoadError: Could not open library 'vips.so.42'`, `executable not found: "identify"`, or a Playwright browser-not-found, build-number mismatch, `Playwright::Error: timeout: expected float, got undefined` or `Running as root without --no-sandbox is not supported`. The fix is almost never a reinstall or a Gemfile edit — it's a PATH, an env var, or a service that isn't running.

FileKindSize
SKILL.mdskill md4.7 KB
assets/web_sandbox_setup.shexecutablescript12.2 KB
references/local-macos.mdmarkdown1.7 KB
references/web-sandbox.mdmarkdown7.5 KB

references/web-sandbox.md

View on GitHub
# Claude Code web sandbox

**The `SessionStart` hook (`.claude/hooks/session-start.sh`) has already set this up**:
Ruby, gems, `node_modules`, libvips + ImageMagick, postgres, redis, the CSS builds, the
Playwright browsers, and `$PATH`/`PG*` exported into your shells. Check with `ruby -v`
and `pg_isready` before setting anything up.

The hook runs `assets/web_sandbox_setup.sh`. Re-run it when the hook didn't finish or an
idle container dropped postgres/redis (a `PG::ConnectionBad`) — it's idempotent:

```bash
bash .claude/skills/sandbox-test-setup/assets/web_sandbox_setup.sh              # setup
bash .claude/skills/sandbox-test-setup/assets/web_sandbox_setup.sh --dev-server # + bin/dev
```

Then:

```bash
eval "$(ruby bin/env --export)"
bundle exec rspec spec/models/bike_spec.rb
LOCAL_CHROME_OVERRIDE=1 bundle exec rspec spec/integration/organized/registrations_search_spec.rb
```

## The seed runs in the background

The script seeds an empty development database after setup, detached so the session
doesn't wait ~95s on it. Wait on it before anything that reads development data — a
screenshot, `rails runner`, `$BASE_URL`:

```bash
until grep -qx 'done\|failed' /tmp/seed.status; do sleep 5; done; cat /tmp/seed.status
```

Log in `/tmp/seed.log`; its `Google API error: request denied` lines are the `.env`
geocoder key being referer-restricted, not a failure. An unseeded database doesn't say
so — counters read zero, comboboxes match nothing. Re-seed from scratch with
`DISABLE_DATABASE_ENVIRONMENT_CHECK=1 bundle exec rails db:reset` (~2 min).

`db:seed` over a seeded database prints `Database already seeded` and changes nothing.

## How the script gets Ruby

Prebuilt Ruby, gem tree and `node_modules` tarballs come from the `web-sandbox-prebuilt`
release (`.github/workflows/web-sandbox-prebuild.yml`). A changed `Gemfile.lock` falls
back to the newest bundle (`bundle-<ver>-latest.txt`) and `bundle install` reconciles;
a `node_modules` miss falls to `npm install`. Stamps skip both on a warm container.

The `prebuilt assets:` block in the output names what resolved; `http 000` means the
host never answered (network policy), not a missing asset. `BINX_PREBUILT_BASE` repoints
the downloads; `BINX_SKIP_PREBUILT=1` forces the source build — `build_ruby()` in the
script, from the cache.ruby-lang.org tarball or a git clone of the tag, ~6 min on 4
cores. Its log looks like it restarts (miniruby, the real build, each ext's
`configure`); it isn't.

**The pin is `.tool-versions`' `ruby` line.** Never fall back to 3.x and patch the
Gemfile — Bundler 4's resolver differs and you'll chase fake regressions.

`Could not open library 'vips.so.42'` or `executable not found: "identify"` (from
`db:seed`) → `apt-get install -y --no-install-recommends libvips42 imagemagick`,
`apt-get update` first if a fetch 404s.

## By hand

The script prints its env block at the end; it's also this:

```bash
export PATH="/opt/ruby-4.0.10/x64/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin"  # service is in /usr/sbin
export LD_LIBRARY_PATH="/opt/ruby-4.0.10/x64/lib:$LD_LIBRARY_PATH"
export PLAYWRIGHT_BROWSERS_PATH=/opt/pw-browsers
export PGHOST=127.0.0.1 PGUSER=rails PGPASSWORD=password  # dev DBs don't take database.yml's CI=1 creds
export LANG=C.UTF-8 LC_ALL=C.UTF-8  # else foreman dies reading .env: invalid byte sequence in US-ASCII

service postgresql start; service redis-server start
sudo -u postgres psql -c "CREATE USER rails WITH SUPERUSER PASSWORD 'password';"  # once
bin/workspace_setup --without_seeds   # .workspace_id, bundle, npm, all four databases
eval "$(ruby bin/env --export)"
```

`bin/setup` loads `db/structure.sql`, so a fresh database has every migration in
seconds; stepping through migrations one by one means something half-created it.

## The dev server

Start it yourself — the container is yours (SKILL.md). It never returns, so background
it and poll:

```bash
nohup bin/dev > /tmp/dev_server.log 2>&1 &
until curl -fs -o /dev/null "$BASE_URL/"; do sleep 5; done   # first boot ~40s
```

It runs the tailwind/dartsass watchers and its own redis (which exits harmlessly when
one is already up). It needs no node — the image's 20.x against the 24.x pin doesn't
matter.

**Poll the artifact, never a duration.** A backgrounded command returns exit 0
immediately, and `sleep 300` has come back in well under 300s here.

## Playwright MCP

A different browser from the specs', configured by the script:

- `/opt/google/chrome/chrome` is a **wrapper script** adding `--no-sandbox`, because
  `.mcp.json` launches without it and we're root. A plain symlink dies with `Running as
  root without --no-sandbox is not supported`, which reads like a missing browser.
  Don't add the flag to `.mcp.json` — it's shared with the human's Mac.
- `/root/.cache/ms-playwright/mcp-auth.json` has to exist (`{"cookies":[],"origins":[]}`).
- If the error names a chromium build the image lacks, `npx playwright install chromium`
  and point the wrapper at the new build.

It **can't reach anything off localhost** — it rejects the egress proxy's CA
(`ERR_CERT_AUTHORITY_INVALID`, even with HTTPS errors ignored), so every page logs
failures for Google Fonts, GTM and Facebook, and a map page for jsdelivr's maplibre.
Those are the sandbox; an app-origin error is the signal. The exception is
`@bikeindex/time-localizer`, pinned to jsdelivr and imported at the top of `application.js`:
its failure means no Stimulus controller connects, so this browser can't exercise one. Screenshots still reach a PR: `github-pr-images` has a
browserless route for here (its `references/web-sandbox.md`).

Selectors: `UI::Forms::Combobox` hides non-matching options rather than removing them,
so use `.hw-combobox__option:not([hidden])`. `browser_click` waits for the page to
settle, so sample sub-second states inside one `browser_evaluate`.

## `:js, type: :system` specs

They run through `capybara-playwright-driver` and the `playwright` npm package — **no
chromedriver, no Selenium**. Needs `LOCAL_CHROME_OVERRIDE=1`: `spec/support/local_chrome.rb`
then adds the root-in-a-container flags.

On a browser-not-found, ask where it's looking:

```bash
npx playwright install --dry-run   # expected install dir + build per browser
npx playwright install chromium-headless-shell   # the build the specs launch, ~10s
```

Where `cdn.playwright.dev` is refused, symlink the image's build under the wanted
number instead (here 1194 → 1223):

```bash
mkdir -p /opt/pw-browsers/chromium_headless_shell-1223
ln -sfn /opt/pw-browsers/chromium_headless_shell-1194/chrome-linux \
        /opt/pw-browsers/chromium_headless_shell-1223/chrome-headless-shell-linux64
ln -sfn headless_shell /opt/pw-browsers/chromium_headless_shell-1194/chrome-linux/chrome-headless-shell
```

## No `gh`

Use the GitHub MCP tools, via the `pr` skill — its appendix maps `gh` to them and
lists their traps. The `pr-guardrails` hook denies `create_pull_request` until that
skill is loaded, and `merge_pull_request` always. A push can open a PR by itself, so
check for one first.

## Network

Set by the environment's network policy, so it moves — probe rather than trust this:
`curl -sIL --max-time 5 -o /dev/null -w "%{http_code}\n" https://<host>`.

As of 2026-09-23, **reachable**: github.com (git and release downloads), api.github.com,
raw.githubusercontent.com (`setup:import_spreadsheets`), rubygems.org,
registry.npmjs.org, cache.ruby-lang.org, cdn.playwright.dev, cdn.jsdelivr.net,
api.mapbox.com. **Refused**: download.ruby-lang.org, and GitHub's archive tarballs
(`codeload.github.com`, `/archive/refs/tags/*.tar.gz`) — `git clone` the tag instead.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall