@spree/docs 0.1.118 → 0.1.120

package/dist/developer/cli/quickstart.md

@@ -141,6 +141,15 @@ Open a Rails console.
 spree console
 ```
 
+### `spree shell`
+
+Open an interactive bash shell inside the web container — the system-shell sibling of `spree console` (Rails) and `spree db:console` (psql). If the web container is down, it starts a one-off container against the same volumes instead. For one-off non-interactive commands, use `spree exec`.
+
+```bash
+spree shell
+spree bash    # alias
+```
+
 ### `spree open`
 
 Open the admin dashboard in the browser.
@@ -264,6 +273,19 @@ spree routes -c Spree::Api::V3::Store::ProductsController   # Filter by controll
 spree routes --expanded
 ```
 
+### `spree rspec`
+
+Run the RSpec test suite inside the web container with `RAILS_ENV=test`, so tests hit the `spree_test` database — never your development data. Everything after `rspec` passes through, so file paths, line numbers, and flags work as usual.
+
+```bash
+spree rspec                                      # full suite
+spree rspec spec/models/spree/brand_spec.rb      # one file
+spree rspec spec/models/spree/brand_spec.rb:15   # one example
+spree rspec --format documentation
+```
+
+Before the first run, create the test database with `spree rails db:test:prepare`. See the [Testing tutorial](../tutorial/testing.md) for writing specs.
+
 ## Running things inside the container
 
 These are passthrough commands — anything after the subcommand reaches the inner Rails/Bundle/Rake invocation as-is. Useful for ad-hoc commands that don't have a dedicated wrapper.

package/dist/developer/tutorial/testing.md

@@ -587,24 +587,33 @@ expect(page).to have_content('Success!')
 
 ## Running Tests
 
-In the Docker flow the container's `DATABASE_URL` points at the development database, so tests need two overrides: a dedicated test database, and DatabaseCleaner's opt-in for non-localhost database hosts (its safeguard against cleaning a database it doesn't own). One-time test database setup:
+### Prepare the test database
 
-```bash Spree CLI (Docker) — one-time setup
-spree exec env RAILS_ENV=test DATABASE_URL=postgres://postgres@postgres:5432/spree_test bin/rails db:prepare
+Tests run against a dedicated `spree_test` database, so your development data is never touched. Create it and load the schema once:
+
+
+```bash Spree CLI (Docker)
+spree rails db:test:prepare
+```
+
+```bash Without Spree CLI
+bin/rails db:test:prepare
 ```
 
-Then run tests:
+
+You rarely need to run this again — `rails_helper.rb` re-syncs the test schema automatically when you add migrations. It's the command to reach for when the test database gets into a broken or out-of-sync state.
+
+### Run the suite
+
+`spree rspec` runs `bundle exec rspec` inside the web container with `RAILS_ENV=test`. Everything after `rspec` is passed through, so file paths, line numbers, and flags work as usual:
 
 
 ```bash Spree CLI (Docker)
-# Define once per shell (or add as an alias):
-alias spree-rspec='spree exec env RAILS_ENV=test DATABASE_URL=postgres://postgres@postgres:5432/spree_test DATABASE_CLEANER_ALLOW_REMOTE_DATABASE_URL=true bundle exec rspec'
-
-spree-rspec                                      # all tests
-spree-rspec spec/models/spree/brand_spec.rb      # specific file
-spree-rspec spec/models/spree/brand_spec.rb:15   # specific test
-spree-rspec --format documentation               # documentation format
-spree-rspec spec/features/                       # only feature tests
+spree rspec                                      # all tests
+spree rspec spec/models/spree/brand_spec.rb      # specific file
+spree rspec spec/models/spree/brand_spec.rb:15   # specific test
+spree rspec --format documentation               # documentation format
+spree rspec spec/features/                       # only feature tests
 ```
 
 ```bash Without Spree CLI
@@ -616,6 +625,29 @@ bundle exec rspec spec/features/                       # only feature tests
 ```
 
 
+<details>
+<summary>Troubleshooting: DatabaseCleaner refuses a remote database URL, or tests hit the development database</summary>
+
+Projects scaffolded before July 2026 set `DATABASE_URL` in `docker-compose.dev.yml`. A URL overrides `config/database.yml` for **every** Rails environment, so in-container tests pointed at the development database and tripped DatabaseCleaner's remote-URL safeguard. Two small changes bring an older project up to date:
+
+1. In `docker-compose.dev.yml`, replace the `DATABASE_URL` entry under `environment:` with host/username parts, so each Rails environment resolves its own database from `database.yml`:
+
+```yaml
+    DATABASE_HOST: postgres
+    DATABASE_USERNAME: postgres
+```
+
+2. In `spec/rails_helper.rb`, force the test environment — the dev container bakes in `RAILS_ENV=development`:
+
+```ruby
+ENV['RAILS_ENV'] = 'test'
+```
+
+Then restart the stack (`Ctrl+C` and `spree dev`) so the container picks up the new environment.
+
+</details>
+
+
 ## Best Practices
 
 
@@ -677,6 +709,7 @@ spec/
 * [Admin Tutorial](admin.md) - Building the admin interface
 * [Extending Core Models](extending-models.md) - Connecting Brands to Products
 * [API Tutorial](api.md) - Creating Brand API endpoints
+* [Spree CLI](../cli/quickstart.md) - `spree rspec` and the other dev workflow commands
 * [RSpec Documentation](https://rspec.info/documentation/) - Official RSpec docs
 * [Factory Bot Documentation](https://github.com/thoughtbot/factory_bot/blob/main/GETTING_STARTED.md) - Factory Bot guide
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spree/docs",
-  "version": "0.1.118",
+  "version": "0.1.120",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",