README

"navtitle": "recipe_onboarding" "shortdesc": "Part of the LLM Platform ecosystem" "source": "Last updated: 2025-08-01"

"outputclass": "concept"

Recipe Onboarding Module

A Drupal module that provides a streamlined onboarding experience for Drupal recipes with AI-powered generation, workflow management, and comprehensive testing capabilities.

Build Process

This module uses modern JavaScript tooling for asset compilation and E2E testing:

Prerequisites

Node.js 18+
npm or yarn
DDEV (for local development)
Playwright browsers (for E2E testing)

Installation

# Install dependencies
npm install

# Install Playwright browsers
npm run install:browsers

Development

# Watch and compile assets during development
npm run watch

# Build for production
npm run build

# Run linting
npm run lint

# Fix linting issues
npm run lint:fix

# Format code with Prettier
npm run prettier

Testing

This module uses Playwright for E2E testing:

# Run all E2E tests
npm test

# Run tests with UI
npm run test:ui

# Debug tests
npm run test:debug

# Run tests in headed mode
npm run test:headed

File Structure

recipe_onboarding/
├── js/                    # JavaScript source files
│   ├── *.js              # Source files (edit these)
│   └── dist/             # Compiled files (gitignored)
├── css/                   # CSS files
├── tests/
│   ├── e2e/              # Playwright E2E tests
│   ├── src/              # PHPUnit tests
│   └── results/          # Test results (gitignored)
├── package.json          # Node.js dependencies for build/test
├── webpack.config.js     # Webpack configuration
└── playwright.config.js  # Playwright configuration

Important Notes

Never commit node_modules/ or js/dist/
Run npm run build before deploying
E2E tests require a running Drupal instance
The js/src/server.ts is being migrated to Drupal services (see MIGRATION_PLAN.md)

Repository Information {#topic-repository-information-2}

Type: Drupal Module (Git Submodule)
GitLab URL: https://gitlab.bluefly.io/llm/recipe_onboarding
Submodule Path: web/modules/custom/recipe_onboarding
Local Path: {{PROJECT_ROOT}}/web/modules/custom/recipe_onboarding

Integration Steps {#topic-integration-steps-3}

Navigate to Individual Repository

# This module is a git submodule, work in its individual repo
cd /path/to/individual/recipe_onboarding/repository

Copy OpenAPI Specification
```
cp openapi.yaml ./
```

Create Contract Testing Structure

mkdir -p tests/src/Functional
mkdir -p tests/features

Add PHPUnit Configuration

<!-- phpunit.xml -->
<testsuite name="recipe_onboarding API Contract Tests">
  <directory>tests/src/Functional</directory>
  <file>tests/src/Functional/*ApiContractTest.php</file>
</testsuite>

Configure JSON:API Entities

# JSON:API is built into Drupal 10 core, just needs configuration
drush en rest restui serialization hal -y
drush cr

Update GitLab CI

include:
  - component: gitlab.bluefly.io/llm/gitlab_components/components/ci-cd/drupal/template@latest
  - component: gitlab.bluefly.io/llm/gitlab_components/components/testing/comprehensive-testing@latest
   
drupal_api_validation:
  extends: .drupal_base
  script:
    - drush en rest restui serialization hal -y
    - drush cr
    - vendor/bin/phpunit tests/src/Functional/*ApiContractTest.php

Commit Changes

git add .
git commit -m "feat: implement API-first architecture for Drupal module
   
- Add OpenAPI 3.1 specification with JSON:API endpoints
- Implement PHPUnit contract tests
- Configure REST and JSON:API endpoints
- Enable API-first development workflow
   
🤖 Generated with API-First Transformation
   
Co-Authored-By: Claude <noreply@anthropic.com>"
git push origin main

JSON:API Endpoints {#topic-json-api-endpoints-4}

Entities: /jsonapi/recipe_onboarding/recipe_onboarding
Custom API: /api/v1/recipe_onboarding/*
Health Check: /api/v1/recipe_onboarding/health

Production Deployment {#topic-production-deployment-5}

Main Platform: https://llm.llm.bluefly.io/api/v1/recipe_onboarding
JSON:API: https://llm.llm.bluefly.io/jsonapi/recipe_onboarding
Documentation: https://docs.llm.bluefly.io/api-docs/recipe_onboarding

Local Development {#topic-local-development-6}

Main Platform: https://llm.local.bluefly.io/api/v1/recipe_onboarding
JSON:API: https://llm.local.bluefly.io/jsonapi/recipe_onboarding
Port Access: http://llm.local.bluefly.io:33000/api/v1/recipe_onboarding

API Testing Best Practices {#topic-api-testing-best-practices-7}

Environment Configuration ✅

Use environment variables instead of hardcoded endpoints
Support multiple environments (dev, staging, prod)
Configuration via dredd.env file

# dredd.yml
endpoint: ${DREDD_ENDPOINT:-http://localhost:8080}

Drupal Testing Standards ✅

Use proper Drupal test classes instead of custom PHP scripts
Follow Drupal testing framework conventions
Extend appropriate base classes (BrowserTestBase, EntityResourceTestBase)

// tests/src/Functional/RecipeApiFunctionalTest.php
class RecipeApiFunctionalTest extends BrowserTestBase {
  // Follows Drupal testing standards
}

// tests/src/Functional/Rest/RecipeResourceTest.php
class RecipeResourceTest extends EntityResourceTestBase {
  // Extends Drupal's REST testing framework
}

Test Organization ✅

tests/
├── src/
│   ├── Functional/
│   │   ├── RecipeApiFunctionalTest.php    # Browser-based API tests
│   │   └── Rest/
│   │       └── RecipeResourceTest.php     # REST resource tests
│   ├── Unit/
│   │   └── Entity/
│   │       └── RecipeTest.php             # Unit tests
│   └── Kernel/
│       └── RecipeKernelTest.php           # Kernel tests
├── contract/
│   └── recipe-api.apib                    # API Blueprint specification
└── scripts/
    └── test-api.sh                        # Test runner script

Contract Testing ✅

API Blueprint specification for API documentation
Automated testing with Dredd
Ensures API consistency across environments

Test Runner Script ✅

Environment-aware configuration
Multiple test types (Drupal, Contract, API)
Proper error handling and colored output

# Run all tests
./scripts/test-api.sh

# With custom endpoint
DREDD_ENDPOINT=https://staging.example.com ./scripts/test-api.sh

Running Tests

Individual Test Types

# Drupal functional tests
ddev drush test:run recipe_onboarding --group=functional

# Drupal REST tests
ddev drush test:run recipe_onboarding --group=rest

# Contract tests with Dredd
dredd tests/contract/recipe-api.apib http://localhost:8080

Complete Test Suite

# Run all tests
./scripts/test-api.sh

Best Practices Summary ✅

Environment Variables: No hardcoded endpoints
Drupal Standards: Use proper test classes
Test Organization: Clear structure and naming
Contract Testing: API Blueprint + Dredd
Automation: Scriptable test runner
Documentation: Clear setup and usage instructions
CI/CD Ready: Environment-aware configuration

Common Anti-Patterns to Avoid ❌

Hardcoded URLs: Use environment variables
Custom PHP Scripts: Use Drupal test framework
Manual Testing: Automate everything
No Documentation: Document setup and usage
Single Environment: Support multiple environments

bluefly / recipe_onboarding

Maintainers

Details