Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Rebalance the testing chapter toward the dashboard
Damian Legawiecaa29a282fa6a
diff --git a/docs/developer/tutorial/testing.mdx b/docs/developer/tutorial/testing.mdxindex 0eef2c1c6e..0bafaa34d4 100644--- a/docs/developer/tutorial/testing.mdx+++ b/docs/developer/tutorial/testing.mdx@@ -1,15 +1,15 @@---title: Testing-description: Test the Brands feature at every layer — model and API specs with RSpec, dashboard tests with Vitest, and one end-to-end Playwright pass.+description: Test the Brands feature — running the generated backend specs, unit-testing the dashboard logic you wrote, and one Playwright pass through the browser.----Each layer gets the test that suits it: fast backend specs for the model and both APIs, component tests for the dashboard, and one end-to-end pass proving the whole path works.+Most of the backend is generated, so most of the testing worth doing is on the code you wrote yourself — which is mostly in the dashboard. This chapter covers the backend briefly, spends longer on the dashboard, and ends with one browser pass proving the layers are actually connected.-Your project arrives with testing already configured — RSpec, FactoryBot, and Spree's own test helpers, including every factory core ships. You can write a spec against `create(:product)` without setting anything up.+## The backend-## Step 1: Run what the generator wrote+Your project arrives with RSpec, FactoryBot and Spree's own helpers already configured — every factory core ships is available, so `create(:product)` works without any setup.-The generator in step 1 already wrote a factory and a controller spec per API side, so this step is mostly filling in rather than starting over:+The generator wrote a factory and a controller spec for each API side:```textserver/spec/factories/spree/brand_factory.rb@@ -17,17 +17,17 @@ server/spec/controllers/spree/api/v3/store/brands_controller_spec.rbserver/spec/controllers/spree/api/v3/admin/brands_controller_spec.rb```-Run them:+Run them, a directory or a single file at a time:```bashspree rspec spec/controllers/spree/api/v3/+spree rspec spec/models/spree/brand_spec.rb+spree rspec spec/models/spree/brand_spec.rb:12 # one example```-The generated factory is the starting point for every other spec — always build records through factories rather than creating them directly, so a change to the model does not mean editing fifty specs.--## Step 2: Model specs+Three conventions carry most of the weight. Build records through **factories** rather than creating them directly, so a model change does not mean editing fifty specs. Add `render_views` to a controller spec, or a broken serializer passes silently. And use the suite's `@default_store` rather than creating another store marked as the default — two of them produce failures that surface far from their cause.-Test what you wrote, not what the framework already guarantees. A presence validation on a required column needs no spec; the association behavior you chose does:+What is worth testing is the behaviour you chose, not what the framework already guarantees:```ruby server/spec/models/spree/brand_spec.rbRSpec.describe Spree::Brand, type: :model do@@ -43,89 +43,90 @@ RSpec.describe Spree::Brand, type: :model doend```-Prefer `build` over `create` when a record does not need to hit the database — it is markedly faster across a suite.--## Step 3: Controller specs+A presence validation on a required column needs no spec. The `dependent: :nullify` you picked in step 1 does, because a future change could quietly turn it into `:destroy` and take the catalog with it.-Controller specs are where edge cases belong: authorization, scoping, filtering, error shapes. Always `render_views`, so a broken serializer fails the spec rather than passing silently:+The generated controller specs are worth one addition — proof that the Ransack allowlist actually permits what the dashboard filters by:```ruby server/spec/controllers/spree/api/v3/store/brands_controller_spec.rb-RSpec.describe Spree::Api::V3::Store::BrandsController, type: :controller do- render_views+it 'filters by name' do+ create(:brand, name: 'Wilson')+ create(:brand, name: 'Penn')- it 'exposes public fields only' do- create(:brand, name: 'Wilson')+ get :index, params: { q: { name_cont: 'wil' }, format: :json }- get :index, params: { format: :json }+ expect(json_response['data'].map { |b| b['name'] }).to eq(['Wilson'])+end+```- record = json_response['data'].first- expect(record['id']).to start_with('brand_')- expect(record).not_to have_key('created_at')- end+Remove `name` from `whitelisted_ransackable_attributes` and this fails — which is the point, because the dashboard column that sorts by it would fail too.- it 'filters by name' do- create(:brand, name: 'Wilson')- create(:brand, name: 'Penn')+## The dashboard- get :index, params: { q: { name_cont: 'wil' }, format: :json }+This is where most of your own code lives, so it is where most of your tests belong. Unlike the backend, the starter ships no test setup — add it once:- expect(json_response['data'].map { |b| b['name'] }).to eq(['Wilson'])- end-end+```bash+cd apps/dashboard+pnpm add -D vitest @playwright/test```-That second example is worth keeping: it proves the Ransack allowlist from step 1 actually permits `name_cont`. Remove `name` from `whitelisted_ransackable_attributes` and this spec fails, which is exactly what you want.+Then two scripts in `apps/dashboard/package.json`:-<Note>- Specs run against a store the suite sets up for you, available as `@default_store`. Use it rather than creating another store marked as the default — two of them in one run produce failures that surface far from their cause.-</Note>+```json+"scripts": {+ "test": "vitest run",+ "test:e2e": "playwright test"+}+```-## Step 4: Dashboard tests+### What is worth a unit test-The dashboard is a TypeScript app, so its code tests with Vitest:+Not components. Rendering a card to assert it shows a brand name tests React, not your feature, and breaks every time the markup moves. Test the **logic between the UI and the API** — the parts with decisions in them.-```bash-cd apps/dashboard && pnpm test-```--Test the client wrappers and any logic in your pages. Mock the HTTP layer rather than the client module, so the test exercises the real request path:+Query keys are the clearest example. Every key must be scoped to the current store, or one store's rows leak into another after a switch. That is a rule a test can hold you to:```ts apps/dashboard/src/brands/client.test.ts-import { http, HttpResponse } from 'msw'-import { setupServer } from 'msw/node'-import { afterAll, afterEach, beforeAll, describe, expect, it } from 'vitest'-import { BrandsClient } from './client'--const server = setupServer(- http.get('*/api/v3/admin/brands', () =>- HttpResponse.json({ data: [{ id: 'brand_k5nR8xLq', name: 'Wilson' }] }),- ),-)--beforeAll(() => server.listen())-afterEach(() => server.resetHandlers())-afterAll(() => server.close())--describe('BrandsClient', () => {- it('lists brands from the admin endpoint', async () => {- const result = await BrandsClient.list({ per_page: 10 })-- expect(result.data).toHaveLength(1)- expect(result.data[0].name).toBe('Wilson')+import { withStoreScope } from '@spree/dashboard'+import { QueryClient } from '@tanstack/react-query'+import { describe, expect, it } from 'vitest'+import { brandInvalidations } from './client'++const STORE = 'store_abc123'++describe('brand cache invalidation', () => {+ it('refreshes the brand list without touching another store', () => {+ const client = new QueryClient()+ client.setQueryData(withStoreScope(['brands'], STORE), [])+ client.setQueryData(withStoreScope(['brands'], 'store_other'), [])++ for (const key of brandInvalidations()) {+ client.invalidateQueries({ queryKey: withStoreScope(key, STORE) })+ }++ const stale = client.getQueryCache().getAll().filter((q) => q.state.isInvalidated)+ expect(stale).toHaveLength(1)})})```-Mocking the HTTP layer rather than the client module means the test exercises the real request path — the URL, the params and the response shape — so a wrong endpoint fails here instead of in the browser.+Driving a real `QueryClient` means the assertion goes through TanStack's own prefix matching rather than a hand-rolled key comparison — so it stays true if the matching rules change.++The same applies to anything else with a decision in it: a function mapping form values to an API payload, a permission predicate deciding whether a nav entry shows, a filter translating table state into Ransack params. Each is a pure function, each is a two-line test.-## Step 5: One end-to-end pass+### What is not worth a unit test++- **Components.** Asserting a card renders text is testing React.+- **`BrandsClient.list` itself.** It is a one-line wrapper around `adminClient.request`. A test would mock the thing it wraps and assert the mock was called — proving nothing about whether the endpoint exists.+- **Anything the compiler already catches.** A wrong prop type is a build failure, not a test case.++That second one is worth dwelling on: the question "does `/brands` actually return brands" cannot be answered by a unit test at all. It needs the real API, which is the next section.++## End to end, through the browserEverything above tests a layer in isolation. One Playwright spec proves the layers are actually connected — a brand created through the Admin API reaches the dashboard screen you built:```ts apps/dashboard/e2e/brands.spec.tsimport { expect, test } from '@playwright/test'-import { createBrand } from './helpers/api'-import { login } from './helpers/login'+import { createBrand, login } from './helpers'test('a brand appears on the brands screen', async ({ page }) => {const name = `Wilson ${Date.now()}`@@ -149,21 +150,21 @@ Two conventions matter here:## What to run before you push-Run the specs for what you changed rather than the whole suite:+Run what you changed, not everything:```bash-spree rspec spec/models/spree/brand_spec.rb-spree rspec spec/controllers/spree/api/v3/+spree rspec spec/models/spree/brand_spec.rb # the backend+cd apps/dashboard && pnpm test # the dashboard```-Pass a file, a directory, or a single example with a line number (`spec/models/spree/brand_spec.rb:12`). Keep the full run for continuous integration, where waiting costs you nothing.+Keep the full suite and the end-to-end pass for continuous integration, where waiting costs you nothing.## You're doneYou have built one feature through every layer of Spree:- A model with a Store API and an Admin API, generated in one command-- A dashboard plugin giving staff a place to manage it+- A dashboard screen giving staff a place to manage it- Storefront pages rendering it through typed SDK calls- Lifecycle events other systems react to- Tests at each layer, plus one pass across all of them