chore: make the development process easier with Storybook

.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,5 @@ node_modules/
 /yarn.lock
 .vscode/
 .env.local
+.yarn/
+storybook-static/

.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,16 @@
+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,
+};

.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,64 @@ 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 contribute by visualizing directly the changes you made the sources through [Storybook](https://storybook.js.org/). 
+
+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.
 
-To stop and prune the simple API Platform backend:
+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.
+
+To access run a command directly inside a container, run:
+```shell
+# Run a command in the php container 
+docker compose exec -T php your-command
+
+# 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:
+Before sending a Pull Request, make sure the tests pass correctly.
+
+#### With Linked Sources
+
+If you have chosen to link `admin` sources, simply run:
 
 ```console
 yarn test
 ```
 
+#### With Admin Through Storybook
+
+If you have chosen to develop with Storybook, you have to build the CI stack first:
+
+```console
+docker compose docker compose -f compose.yaml -f compose.ci.yaml up
+```
+
+Once the containes are healthy, run 
+```console
+# fonctional tests
+docker compose exec -T pwa yarn test
+
+# End to end tests (Running with Storybook interactions https://storybook.js.org/docs/writing-stories/play-function)
+docker compose exec -T pwa yarn storybook:test --url http://127.0.0.1:3000
+```
+
 ### 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,24 +2,20 @@
 
 
 # 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
@@ -28,12 +24,15 @@ CMD ["sh", "-c", "yarn install; yarn storybook"]
 
 FROM base as ci
 
-COPY --link package.json yarn.lock ./
+COPY --link package.json yarn.lock .yarnrc.yml ./
+
 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
+
+CMD ["sh", "-c", "yarn storybook:build && yarn storybook:serve -p 3000"]

api/bin/phpunit

@@ -0,0 +1,23 @@
+#!/usr/bin/env php
+<?php
+
+if (!ini_get('date.timezone')) {
+    ini_set('date.timezone', 'UTC');
+}
+
+if (is_file(dirname(__DIR__).'/vendor/phpunit/phpunit/phpunit')) {
+    if (PHP_VERSION_ID >= 80000) {
+        require dirname(__DIR__).'/vendor/phpunit/phpunit/phpunit';
+    } else {
+        define('PHPUNIT_COMPOSER_INSTALL', dirname(__DIR__).'/vendor/autoload.php');
+        require PHPUNIT_COMPOSER_INSTALL;
+        PHPUnit\TextUI\Command::main();
+    }
+} else {
+    if (!is_file(dirname(__DIR__).'/vendor/symfony/phpunit-bridge/bin/simple-phpunit.php')) {
+        echo "Unable to find the `simple-phpunit.php` script in `vendor/symfony/phpunit-bridge/bin/`.\n";
+        exit(1);
+    }
+
+    require dirname(__DIR__).'/vendor/symfony/phpunit-bridge/bin/simple-phpunit.php';
+}

api/composer.json

@@ -27,7 +27,9 @@
         "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",

api/config/bundles.php

@@ -10,4 +10,8 @@
     Symfony\Bundle\MakerBundle\MakerBundle::class => ['dev' => true],
     Doctrine\Bundle\MigrationsBundle\DoctrineMigrationsBundle::class => ['all' => true],
     Symfony\Bundle\DebugBundle\DebugBundle::class => ['dev' => true, 'test' => true],
+    Symfony\Bundle\MonologBundle\MonologBundle::class => ['all' => true],
+    Symfony\Bundle\TwigBundle\TwigBundle::class => ['all' => true],
+    Twig\Extra\TwigExtraBundle\TwigExtraBundle::class => ['all' => true],
+    Symfony\Bundle\WebProfilerBundle\WebProfilerBundle::class => ['dev' => true, 'test' => true],
 ];

api/config/packages/cache.yaml

@@ -0,0 +1,19 @@
+framework:
+    cache:
+        # Unique name of your app: used to compute stable namespaces for cache keys.
+        #prefix_seed: your_vendor_name/app_name
+
+        # The "app" cache stores to the filesystem by default.
+        # The data in this cache should persist between deploys.
+        # Other options include:
+
+        # Redis
+        #app: cache.adapter.redis
+        #default_redis_provider: redis://localhost
+
+        # APCu (not recommended with heavy random-write workloads as memory fragmentation can cause perf issues)
+        #app: cache.adapter.apcu
+
+        # Namespaced pools use the above "app" backend by default
+        #pools:
+            #my.dedicated.cache: null

api/config/packages/debug.yaml

@@ -0,0 +1,5 @@
+when@dev:
+    debug:
+        # Forwards VarDumper Data clones to a centralized server allowing to inspect dumps on CLI or in your browser.
+        # See the "server:dump" command to start a new server.
+        dump_destination: "tcp://%env(VAR_DUMPER_SERVER)%"