From 589c8845f5adac76347c3fce022837f2ffc6e94e Mon Sep 17 00:00:00 2001 From: Raghu Betina Date: Sun, 11 Oct 2026 18:16:49 -0500 Subject: [PATCH] Run an app's specs before its first preview From the next service deploy, a generated app's AGENTS.md says to run its specs before other work, and its README says to build the assets and run the specs before the first preview. The workshop notes sent the agent from Compile straight to bin/dev, and they took precedence over the app's own guides, so they would have skipped that step. The notes now set up the app and run its specs first, say what a failure in that first run means, and let the app's AGENTS.md and README govern testing. A NotImplementedError that names behavior listed under Behavior to write is work to do; any other failure is a First Draft defect. Both hold before the deploy, when apps have no stubs and every failure is a defect. System specs need a Selenium service that this Codespace leaves stopped, and only the bin/ci recipe in AGENTS.md started it. That file moves away at root Compile, so a plain bundle exec rspec failed every system spec. The notes now carry a start, use and stop recipe for every spec run. It starts the app's own Compose service, whose health check makes the wait mean ready, in the running container's Compose project, where Rails and the browser share a network. It runs the specs only once the browser is ready, always stops it, and keeps a failure's exit status. The status variable avoids zsh's read-only status. --- .devcontainer/workshop/app-instructions.md | 30 +++++++++++++++++++--- 1 file changed, 27 insertions(+), 3 deletions(-) diff --git a/.devcontainer/workshop/app-instructions.md b/.devcontainer/workshop/app-instructions.md index ac02f05..57d0d4c 100644 --- a/.devcontainer/workshop/app-instructions.md +++ b/.devcontainer/workshop/app-instructions.md @@ -1,16 +1,40 @@ # Workshop apps in this Codespace Added by the Drawing Board. Where these notes differ from an app's own guides or a provider's -guidance, follow these notes. Never print secrets, show a file that holds one, or ask the user to -paste one into the chat. +guidance, follow these notes, except on testing, where the app's `AGENTS.md` and README govern. +Never print secrets, show a file that holds one, or ask the user to paste one into the chat. ## Files the user wants to use - The user adds files, such as a design zip, by dragging them into VS Code's file list. Unzip a design into the project folder before the first Compile. Compiling into the current folder keeps it under `.firstdraft/design/`. +## Setup and specs +- After Compile, set up the app, build its assets and run its specs as its README says, before the + first preview. In that first run, a `NotImplementedError` that names behavior listed under the + README's **Behavior to write** is work to do: write that behavior until its specs pass. Any other + failure in that run is a First Draft defect: tell the user which spec failed and its error. Never + edit or delete a generated spec to make it pass. +- System specs need a Selenium browser that this Codespace does not start by itself. From the app's + root, start it before every spec run (all specs, one spec file, or `bin/ci`) and stop it + afterward, even when specs fail. Run these lines as one command, with your spec command in place + of `bundle exec rspec`. They run the specs only once the browser is ready, stop the browser + either way, and fail if any step fails. The app's Compose file starts the browser in this + Codespace's Compose project, where it and Rails can reach each other. The first start downloads + the browser image and can take a few minutes. + + ```sh + spec_run_status=0 + project="$(docker inspect --format '{{ index .Config.Labels "com.docker.compose.project" }}' "$HOSTNAME")" && + docker compose --project-name "$project" --file .devcontainer/compose.yaml up --detach --wait selenium && + bundle exec rspec || spec_run_status=$? + docker compose --project-name "$project" --file .devcontainer/compose.yaml stop selenium || spec_run_status=1 + (exit "$spec_run_status") + ``` + ## Web app -- Start the web app in the background and keep it running all session: +- Once the specs have run after Compile, start the web app in the background and keep it + running all session: `bin/dev log/bin-dev.log 2>&1`. Rails already admits this Codespace's forwarded address. Open `https://$CODESPACE_NAME-3000.$GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN` for the user with `bash ~/.workshop/open.sh `, and also give them that link. Keep port 3000