chore: make the development process easier with Storybook (#541)

.github/workflows/storybook.yml

@@ -23,38 +23,31 @@ jobs:
         name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
       -
-        name: Build Docker images
-        uses: docker/bake-action@v4
-        with:
-          pull: true
-          load: true
-          files: |
-            compose.yaml
-          set: |
-            *.cache-from=type=gha,scope=${{github.ref}}
-            *.cache-from=type=gha,scope=refs/heads/main
-            *.cache-to=type=gha,scope=${{github.ref}},mode=max
+          name: Build Docker images
+          uses: docker/bake-action@v4
+          with:
+              pull: true
+              load: true
+              files: |
+                compose.yaml
+                compose.ci.yaml
+              set: |
+                *.cache-from=type=gha,scope=${{github.ref}}
+                *.cache-from=type=gha,scope=refs/heads/main
+                *.cache-to=type=gha,scope=${{github.ref}},mode=max
       -
         name: Start services
         run: docker compose -f compose.yaml -f compose.ci.yaml up --wait --no-build
-      -
-        name: Check HTTP reachability
-        run: curl -v --fail-with-body http://localhost
-      -
-        name: Check PWA reachability
-        run: "curl -vk --fail-with-body -H 'Accept: text/html' https://localhost"
-      -
-        name: Check API reachability
-        run: "curl -vk --fail-with-body -H 'Accept: application/ld+json' https://localhost"
       -
         name: Create test database
         run: docker compose exec -T php bin/console -e test doctrine:database:create
       -
         name: Run migrations
         run: docker compose exec -T php bin/console -e test doctrine:migrations:migrate --no-interaction
-      # -
-      #   name: Doctrine Schema Validator
-      #   run: docker compose exec -T pwa pnpm run storybook
+      -
+        name: Run interactions tests
+        run: docker compose exec -T pwa yarn storybook:test --url http://127.0.0.1:3000 --maxWorkers 1
+
   lint:
     name: Docker Lint
     runs-on: ubuntu-latest

.gitignore

@@ -3,3 +3,6 @@ node_modules/
 /yarn.lock
 .vscode/
 .env.local
+.yarn/
+storybook-static/
+.cache/

.storybook/main.ts

@@ -7,6 +7,8 @@ const config: StorybookConfig = {
     '@storybook/addon-essentials',
     '@storybook/addon-onboarding',
     '@storybook/addon-interactions',
+    '@storybook/addon-mdx-gfm',
+    '@storybook/addon-webpack5-compiler-babel'
   ],
   framework: {
     name: '@storybook/react-webpack5',
@@ -17,6 +19,7 @@ const config: StorybookConfig = {
   },
   env: (config) => ({
     ...config,
+    ENTRYPOINT: process.env.ENTRYPOINT ?? 'https://localhost',
   }),
   async webpackFinal(config, { configType }) {
     config.resolve = {

.storybook/preview.ts

@@ -2,7 +2,6 @@ import type { Preview } from '@storybook/react';
 
 const preview: Preview = {
   parameters: {
-    actions: { argTypesRegex: '^on[A-Z].*' },
     controls: {
       matchers: {
         color: /(background|color)$/i,

.storybook/test-runner-jest.ts

@@ -0,0 +1,23 @@
+import { getJestConfig } from '@storybook/test-runner';
+
+/**
+ * Jest configuration for running tests in Storybook.
+ */
+module.exports = {
+  // The default Jest configuration comes from @storybook/test
+  ...getJestConfig(),
+
+  /**
+   * Add your own overrides below, and make sure
+   * to merge testRunnerConfig properties with your own.
+   * @see https://jestjs.io/docs/configuration
+   */
+  testTimeout: 30000,
+  testEnvironmentOptions: {
+    'jest-playwright': {
+      launchOptions: {
+        args: ['--ignore-certificate-errors']
+      }
+    }
+  }
+};

.yarnrc.yml

@@ -0,0 +1 @@
+nodeLinker: node-modules

CONTRIBUTING.md

@@ -27,10 +27,10 @@ Please base your changes on the `main` branch.
 ### Two ways to write your patch
 
 You can patch `@api-platform/admin` by two different ways:
-- by linking `@api-platform/admin` sources to an existing project;
-- by installing this project and running it through Storybook.
+- if you already have a project in progress: read [Linking the Source Version to an Existing Project](#linking-the-source-version-to-an-existing-project);
+- if you do not have an existing project: read [Running Admin Through Storybook](#running-admin-through-storybook).
 
-#### Linking the Source Version to an existing project
+#### Linking the Source Version to an Existing Project
 
 If you already have a project in progress, you can develop directly from it.
 
@@ -95,28 +95,52 @@ yarn dev --force
 
 > You can now hack in the cloned repository of `api-platform-admin`.
 
-#### Running Admin through Storybook
+#### Running Admin Through Storybook
 
-If you don't have an existing API Platform application, or don't want to use `yarn link`, you can use one of the bundled example APIs, and visualize the admin through [Storybook](https://storybook.js.org/).
+If you do not have an existing project, you can use [Storybook](https://storybook.js.org/) to visualize changes in the source code, and test them. 
+
+This development stack consists of two Docker containers: 
+- `pwa`: containing the `<Admin>` sources and Storybook;
+- `php`: holding the API sources.
+
+Additionally, this method allows testing the integration between API Platform and the `admin` component by writing stories, scenarios and tests.
 
 Install everything:
 
 ```shell
 docker compose up
 ```
 
-Go to http://localhost, accept the self-signed certificate, and see the running Admin.
+Before accessing the Storybook instance, make sure to go to https://localhost to accept the self-signed certificate. Once it's done, you'll see the API documentation running on a customized version of Swagger UI.
+
+Now you can go to http://localhost:3000/ to see the Storybook instance in action. The changes you'll make in the source code will be hot-reloaded.
+
+> Tips: you can run Storybook directly in your local machine by running `yarn storybook`. It will take another port, usually 3001. Make sure to have the API running before.
+
+To run a command directly inside a container, run:
+```shell
+# Run a command in the php container 
+docker compose exec -T php your-command
 
-To stop and prune the simple API Platform backend:
+# Run a command in the pwa container
+docker compose exec -T pwa your-command
+```
 
 ### Testing Your Changes
 
 Before sending a Pull Request, make sure the tests pass correctly:
 
-```console
+```shell
+# Functional tests
 yarn test
+# End to end tests
+yarn test-storybook --url http://127.0.0.1:3000/
 ```
 
+If you add a new feature, don't forget to add tests for it. 
+- Functionnal tests are written with [Jest](https://jestjs.io/) and [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/);
+- End-to-end tests are written with [Storybook play funcitons](https://storybook.js.org/docs/writing-stories/play-function/).
+
 ### Matching Coding Standards
 
 The API Platform Admin project follows coding standards inspired by the [Airbnb JavaScript style guide](https://github.com/airbnb/javascript).

Dockerfile

@@ -2,38 +2,37 @@
 
 
 # Versions
-FROM node:20-alpine AS node_upstream
+FROM node:20-bookworm AS node_upstream
 
 
 # Base stage for dev and build
 FROM node_upstream AS base
 
-# Check https://github.com/nodejs/docker-node/tree/b4117f9333da4138b03a546ec926ef50a31506c3#nodealpine to understand why libc6-compat might be needed.
-# hadolint ignore=DL3018
-RUN apk add --no-cache libc6-compat
-
 WORKDIR /srv/app
 
 RUN corepack enable && \
 	corepack prepare --activate yarn@*
 
+ENV HOSTNAME localhost
 EXPOSE 3000
 ENV PORT 3000
-ENV HOSTNAME localhost
-
-# Development image
-FROM base as dev
 
-CMD ["sh", "-c", "yarn install; yarn storybook"]
-
-FROM base as ci
+COPY --link package.json yarn.lock .yarnrc.yml ./
 
-COPY --link package.json yarn.lock ./
 RUN set -eux; \
-	yarn
+	yarn && yarn cache clean
 
 # copy sources
 COPY --link . ./
-RUN yarn storybook:build
 
-CMD ["yarn", "serve"]
+RUN set -eux; \
+	yarn playwright install --with-deps && yarn cache clean
+
+# Development image
+FROM base as dev
+
+CMD ["sh", "-c", "yarn storybook"]
+
+FROM base as ci
+
+CMD ["sh", "-c", "yarn storybook:build && yarn storybook:serve -p 3000"]

api/composer.json

@@ -27,15 +27,12 @@
         "symfony/serializer": "6.4.*",
         "symfony/twig-bundle": "6.4.*",
         "symfony/validator": "6.4.*",
-        "symfony/yaml": "6.4.*"
+        "symfony/yaml": "6.4.*",
+        "twig/extra-bundle": "^2.12|^3.0",
+        "twig/twig": "^2.12|^3.0"
     },
     "require-dev": {
-        "api-platform/schema-generator": "^5.0",
-        "symfony/browser-kit": "6.4.*",
-        "symfony/css-selector": "6.4.*",
         "symfony/debug-bundle": "6.4.*",
-        "symfony/maker-bundle": "^1.44",
-        "symfony/phpunit-bridge": "6.4.*",
         "symfony/stopwatch": "6.4.*",
         "symfony/var-dumper": "6.4.*",
         "symfony/web-profiler-bundle": "6.4.*"