@qlover/create-app 0.7.15 → 0.9.0

package/dist/templates/react-app/README.en.md

@@ -1,19 +1,19 @@
 # FE-React Template
 
-A modern React frontend project template with integrated practical features and best practices.
+A modern React frontend project template integrated with multiple practical features and best practices.
 
 [中文](./README.md)
 
-## 🌟 Features
+## 🌟 Highlights
 
-- 🚀 Fast development experience with Vite
+- 🚀 Fast development experience based on Vite
 - 🎨 Theme system integrated with Tailwind CSS
-- 🌍 Comprehensive internationalization support (Chinese & English)
+- 🌍 Complete internationalization support (Chinese and English)
 - 🔄 TypeScript-based IOC container
 - 📡 Unified API request handling
-- 🎮 Controller pattern for state management
-- 📦 Package management with pnpm
-- 🧪 Built-in test support
+- 🎮 Controller pattern state management
+- 📦 Package management using pnpm
+- 🧪 Built-in testing support
 
 ## 🔧 Requirements
 
@@ -23,14 +23,14 @@ A modern React frontend project template with integrated practical features and
 ## 📁 Project Structure
 
 ```tree
-├── config/                 # Configuration directory
-│   ├── app.router.json     # Router page configuration
+├── config/                 # Configuration files directory
+│   ├── app.router.json     # Route page configuration
 │   ├── common.ts           # Application common configuration
-│   ├── app.router.json     # Router configuration
-│   ├── i18n.ts             # I18n configuration
+│   ├── app.router.json     # Route configuration
+│   ├── i18n.ts             # Internationalization configuration
 │   └── theme.json          # Theme configuration
 ├── lib/                    # Common library directory
-├── public/                 # Static resources directory
+├── public/                 # Static assets directory
 ├── src/
 │   ├── base/           # Base code
 │   ├── core/           # Core code
@@ -63,51 +63,69 @@ pnpm build
 ### Run Tests
 
 ```bash
+# Run unit tests
 pnpm test
+
+# Run E2E tests
+pnpm test:e2e
+
+# Run E2E tests (UI mode)
+pnpm test:e2e:ui
 ```
 
 ## 📚 Documentation Guide
 
 The project provides detailed development documentation covering all major features and best practices:
 
-### Basic Documentation
-- [Project Overview](./docs/en/index.md) - Project introduction and quick start guide
-- [Project Structure](./docs/en/project-structure.md) - Detailed project directory structure explanation
-- [Development Guide](./docs/en/development-guide.md) - Project development specifications and best practices
-- [Environment Configuration](./docs/en/env.md) - Environment variables and configuration management
-- [Global Configuration](./docs/en/global.md) - Application global configuration and settings
-
-### Core Features
-- [Bootstrap Process](./docs/en/bootstrap.md) - Application startup process and lifecycle management
-- [IOC Container](./docs/en/ioc.md) - Dependency injection system usage guide
-- [Router Management](./docs/en/router.md) - Router configuration and page navigation
-- [State Management](./docs/en/store.md) - Application state management solution
-- [Request Handling](./docs/en/request.md) - API request handling mechanism
-
-### Feature Extensions
-- [Internationalization](./docs/en/i18n.md) - Multi-language support and translation management
-- [Theme System](./docs/en/theme.md) - Theme configuration and dark mode support
-- [TypeScript Guide](./docs/en/typescript-guide.md) - TypeScript usage specifications and best practices
+### 🚀 Getting Started
+
+- **[📖 Project Documentation](./docs/en/index.md)** - Architecture overview, core concepts, and complete documentation navigation
+- **[Development Guide](./docs/en/development-guide.md)** - 📝 Complete page development process
+
+### 🎯 Core Features
+
+- **[Bootstrap Initializer](./docs/en/bootstrap.md)** - ⚡ Application startup and initialization
+- **[IOC Container](./docs/en/ioc.md)** - 🔌 Dependency injection and UI separation
+- **[Store State Management](./docs/en/store.md)** - 📡 How the application layer notifies the UI layer
+- **[Environment Variable Management](./docs/en/env.md)** - ⚙️ Multi-environment configuration
+- **[Internationalization](./docs/en/i18n.md)** - 🌍 i18n Key and translation management
+
+### 🧪 Testing Documentation
+
+- **[Playwright E2E Testing](./docs/en/playwright/)** - 🎭 Complete end-to-end testing documentation
+  - [Overview](./docs/en/playwright/overview.md)
+  - [Quick Start](./docs/en/playwright/quickstart.md)
+  - [Testing Guide](./docs/en/playwright/testing-guide.md)
+  - [Setup Complete](./docs/en/playwright/setup-complete.md)
+- [Unit Testing Guide](./docs/en/test-guide.md) - Vitest unit testing
+
+### 📖 Additional Documentation
+
+- [Why Disable Global Variables](./docs/en/why-no-globals.md) - Global variable usage guidelines
+- [Route Management](./docs/en/router.md) - Route configuration instructions
+- [Theme System](./docs/en/theme.md) - Theme configuration and switching
+- [Request Handling](./docs/en/request.md) - API request handling
+- [TypeScript Guide](./docs/en/typescript-guide.md) - TypeScript conventions
 
 ## 🔨 Core Features
 
 ### IOC Container
 
 - TypeScript-based dependency injection system
-- Support for automatic service registration and dependency management
-- Complete type inference
+- Supports automatic service registration and dependency management
+- Provides complete type inference
 
 ### Environment Configuration
 
-[Vite Environment Variables and Modes](https://vitejs.dev/guide/env-and-mode.html)
+[Vite Environment Variables and Modes](https://cn.vite.dev/guide/env-and-mode#env-variables-and-modes)
 
-`vite dev` default NODE_ENV is 'development', it will load possible `.env[mode]` files, e.g., .env.local -> .env
+`vite dev` defaults NODE_ENV to development, it will load possible `.env[mode]` files, such as .env.local -> .env
 
-`vite build` default NODE_ENV is 'production', it will load possible `.env[mode]` files, e.g., .env.production -> .env
+`vite build` defaults NODE_ENV to production, it will load possible `.env[mode]` files, such as .env.production -> .env
 
 Node.js NODE_ENV only supports development, production, test
 
-This is completely different from mode in vite. Mode can be specified with `--mode` to load different env configurations.
+This is completely different from mode in vite, mode can specify different modes through `--mode` to load different env configurations
 
 For example:
 
@@ -118,21 +136,21 @@ vite dev --mode local # Load .env.local
 
 ### Internationalization Support
 
-- Complete i18n solution based on i18next
-- Support for Chinese (zh) and English (en) language switching
-- Automatic i18n resource generation based on TypeScript comments
+- Complete internationalization solution based on i18next
+- Supports Chinese (zh) and English (en) bilingual switching
+- Automatic internationalization resource generation based on TypeScript comments
 - URL path language detection and switching
-- Built-in language switcher component
+- Built-in language switching component
 
 ### Theme System
 
 - Theme configuration based on Tailwind CSS
-- Support for dark/light mode
+- Supports dark/light mode
 - Custom design token system
 
 ### API Integration
 
-The project provides a powerful API request handling mechanism based on a plugin architecture:
+The project provides a powerful API request handling mechanism based on a plugin architecture design:
 
 #### Request Controller
 
@@ -182,24 +200,24 @@ Provides multiple out-of-the-box controllers:
 
 ## 🛠️ Development Guide
 
-### API Development Standards
+### API Development Specifications
 
 1. Define interfaces in `src/base/apis`
-2. Support for Mock data configuration
+2. Support Mock data configuration
 
-### Adding New Pages
+### Adding New Pages Process
 
-1. Create page component in `src/pages`
+1. Create page components in `src/pages`
 2. Update `config/app.router.json`
 3. Add corresponding controller (if needed)
 
 ### Build Optimization
 
-The project uses Vite for building and includes the following optimizations:
+The project uses Vite for building and has been optimized with the following:
 
 #### Code Splitting
 
-Automatic intelligent code splitting into the following main chunks:
+Automatic intelligent code splitting, dividing code into the following main chunks:
 
 - react-vendor: React core library
 - antd-core: Ant Design core components
@@ -214,7 +232,7 @@ Automatic intelligent code splitting into the following main chunks:
 build: {
   // Chunk size warning limit set to 600kb
   chunkSizeWarningLimit: 600,
-  // Use terser for code compression
+  // Use terser for code minification
   minify: 'terser',
   terserOptions: {
     compress: {
@@ -234,18 +252,18 @@ build: {
 
 - Use `@qlover/corekit-bridge/vite-env-config` to manage environment variables
 - Automatically inject application name and version information
-- Support for environment variable prefix configuration
+- Support environment variable prefix configuration
 
 #### Style Configuration
 
-- Integrate Tailwind CSS
-- Load Ant Design component styles on demand
+- Integrated with Tailwind CSS
+- On-demand loading of Ant Design component styles
 - Support theme mode override
 
 #### Development Server
 
 ```bash
-# Default port 3200, configurable via environment variable
+# Default port 3200, can be configured via environment variables
 VITE_SERVER_PORT=3000 pnpm dev
 ```
 
@@ -254,4 +272,3 @@ VITE_SERVER_PORT=3000 pnpm dev
 - Use Vitest for unit testing
 - Support JSDOM environment
 - Built-in test tool configuration
-``` 

package/dist/templates/react-app/README.md

@@ -63,31 +63,48 @@ pnpm build
 ### 运行测试
 
 ```bash
+# 运行单元测试
 pnpm test
+
+# 运行 E2E 测试
+pnpm test:e2e
+
+# 运行 E2E 测试（UI 模式）
+pnpm test:e2e:ui
 ```
 
 ## 📚 文档指南
 
 项目提供了详细的开发文档，涵盖了所有主要功能和最佳实践：
 
-### 基础文档
-- [项目概述](./docs/zh/index.md) - 项目整体介绍和快速开始指南
-- [项目结构](./docs/zh/project-structure.md) - 详细的项目目录结构说明
-- [开发指南](./docs/zh/development-guide.md) - 项目开发规范和最佳实践
-- [环境配置](./docs/zh/env.md) - 环境变量和配置管理说明
-- [全局配置](./docs/zh/global.md) - 应用全局配置和设置说明
-
-### 核心功能
-- [启动流程](./docs/zh/bootstrap.md) - 应用启动流程和生命周期管理
-- [IOC容器](./docs/zh/ioc.md) - 依赖注入系统的使用说明
-- [路由管理](./docs/zh/router.md) - 路由配置和页面导航说明
-- [状态管理](./docs/zh/store.md) - 应用状态管理方案说明
-- [请求处理](./docs/zh/request.md) - API 请求处理机制说明
-
-### 功能扩展
-- [国际化](./docs/zh/i18n.md) - 多语言支持和翻译管理
-- [主题系统](./docs/zh/theme.md) - 主题配置和暗色模式支持
-- [TypeScript指南](./docs/zh/typescript-guide.md) - TypeScript 使用规范和最佳实践
+### 🚀 快速上手
+
+- **[📖 项目文档](./docs/zh/index.md)** - 架构概览、核心理念和完整文档导航
+- **[开发指南](./docs/zh/development-guide.md)** - 📝 完整的页面开发流程
+
+### 🎯 核心功能
+
+- **[Bootstrap 启动器](./docs/zh/bootstrap.md)** - ⚡ 应用启动和初始化
+- **[IOC 容器](./docs/zh/ioc.md)** - 🔌 依赖注入和 UI 分离
+- **[Store 状态管理](./docs/zh/store.md)** - 📡 应用层如何通知 UI 层
+- **[环境变量管理](./docs/zh/env.md)** - ⚙️ 多环境配置
+- **[国际化](./docs/zh/i18n.md)** - 🌍 i18n Key 和翻译管理
+
+### 🧪 测试文档
+
+- **[Playwright E2E 测试](./docs/zh/playwright/)** - 🎭 端到端测试完整文档
+  - [快速入门](./docs/zh/playwright/quickstart.md)
+  - [详细测试指南](./docs/zh/playwright/testing-guide.md)
+  - [设置完成指南](./docs/zh/playwright/setup-complete.md)
+- [单元测试指南](./docs/zh/test-guide.md) - Vitest 单元测试
+
+### 📖 辅助文档
+
+- [为什么要禁用全局变量](./docs/zh/why-no-globals.md) - 全局变量使用规范
+- [路由管理](./docs/zh/router.md) - 路由配置说明
+- [主题系统](./docs/zh/theme.md) - 主题配置和切换
+- [请求处理](./docs/zh/request.md) - API 请求处理
+- [TypeScript 指南](./docs/zh/typescript-guide.md) - TypeScript 规范
 
 ## 🔨 核心功能
 

package/dist/templates/react-app/__tests__/__mocks__/BootstrapTest.ts

@@ -0,0 +1,14 @@
+import type { BootstrapClientArgs } from '@/core/bootstraps/BootstrapClient';
+import { BootstrapClient } from '@/core/bootstraps/BootstrapClient';
+import { testIOC } from './testIOC/TestIOC';
+
+export interface BootstrapTestArgs extends Omit<BootstrapClientArgs, 'ioc'> {
+  ioc?: BootstrapClientArgs['ioc'];
+}
+
+export class BootstrapTest {
+  static async main(args: BootstrapTestArgs): Promise<BootstrapClientArgs> {
+    const result = await BootstrapClient.main({ ...args, ioc: testIOC });
+    return result;
+  }
+}

package/dist/templates/react-app/__tests__/__mocks__/MockAppConfit.ts

@@ -1,5 +1,5 @@
-import { EnvConfigInterface } from '@qlover/corekit-bridge';
 import { name, version } from '../../package.json';
+import type { EnvConfigInterface } from '@qlover/corekit-bridge';
 
 export class MockAppConfig implements EnvConfigInterface {
   appName = name;

package/dist/templates/react-app/__tests__/__mocks__/MockDialogHandler.ts

@@ -1,6 +1,6 @@
-import { InteractionHubInterface } from '@/base/port/InteractionHubInterface';
-import { AntdStaticApiInterface } from '@brain-toolkit/antd-theme-override/react';
 import { vi } from 'vitest';
+import type { InteractionHubInterface } from '@/base/port/InteractionHubInterface';
+import type { AntdStaticApiInterface } from '@brain-toolkit/antd-theme-override/react';
 
 export class MockDialogHandler
   implements InteractionHubInterface, AntdStaticApiInterface

package/dist/templates/react-app/__tests__/__mocks__/MockLogger.ts

@@ -1,5 +1,5 @@
-import { LoggerInterface } from '@qlover/logger';
 import { vi } from 'vitest';
+import type { LoggerInterface } from '@qlover/logger';
 
 export class MockLogger implements LoggerInterface {
   info = vi.fn();

package/dist/templates/react-app/__tests__/__mocks__/components/TestApp.tsx

@@ -0,0 +1,45 @@
+import { TestBootstrapsProvider } from './TestBootstrapsProvider';
+
+interface TestAppProps {
+  children: React.ReactNode;
+  /**
+   * Initial URL path for the router
+   * @default ['/en/']
+   */
+  routerInitialEntries?: string[];
+  /**
+   * Initial index of the entries array
+   * @default 0
+   */
+  routerInitialIndex?: number;
+}
+
+/**
+ * TestApp - Complete test wrapper with IOC and Router
+ *
+ * Usage:
+ * ```tsx
+ * import { TestApp } from '__tests__/__mocks__/components/TestApp';
+ *
+ * render(
+ *   <TestApp routerInitialEntries={['/en/dashboard']}>
+ *     <YourComponent />
+ *   </TestApp>
+ * );
+ * ```
+ */
+export function TestApp({
+  children,
+  routerInitialEntries,
+  routerInitialIndex
+}: TestAppProps) {
+  return (
+    <TestBootstrapsProvider
+      data-testid="TestApp"
+      routerInitialEntries={routerInitialEntries}
+      routerInitialIndex={routerInitialIndex}
+    >
+      {children}
+    </TestBootstrapsProvider>
+  );
+}

package/dist/templates/react-app/__tests__/__mocks__/components/TestBootstrapsProvider.tsx

@@ -0,0 +1,34 @@
+import { IOCContext } from '@/uikit/contexts/IOCContext';
+import { TestRouter } from './TestRouter';
+import { testIOC } from '../testIOC/TestIOC';
+
+export function TestBootstrapsProvider({
+  children,
+  routerInitialEntries,
+  routerInitialIndex
+}: {
+  children: React.ReactNode;
+  /**
+   * Initial URL path for the router
+   * @default ['/en/']
+   */
+  routerInitialEntries?: string[];
+  /**
+   * Initial index of the entries array
+   * @default 0
+   */
+  routerInitialIndex?: number;
+}) {
+  const IOC = testIOC.create();
+
+  return (
+    <IOCContext.Provider data-testid="TestBootstrapsProvider" value={IOC}>
+      <TestRouter
+        initialEntries={routerInitialEntries}
+        initialIndex={routerInitialIndex}
+      >
+        {children}
+      </TestRouter>
+    </IOCContext.Provider>
+  );
+}

package/dist/templates/react-app/__tests__/__mocks__/components/TestRouter.tsx

@@ -0,0 +1,46 @@
+import { MemoryRouter } from 'react-router-dom';
+import type { ReactNode } from 'react';
+
+interface TestRouterProps {
+  children: ReactNode;
+  /**
+   * Initial URL path for the router
+   * @default '/en/'
+   */
+  initialEntries?: string[];
+  /**
+   * Initial index of the entries array
+   * @default 0
+   */
+  initialIndex?: number;
+}
+
+/**
+ * TestRouter - A reusable router wrapper for tests
+ *
+ * Usage:
+ * ```tsx
+ * import { TestRouter } from '__tests__/__mocks__/components/TestRouter';
+ *
+ * render(
+ *   <TestRouter initialEntries={['/en/dashboard']}>
+ *     <YourComponent />
+ *   </TestRouter>
+ * );
+ * ```
+ */
+export function TestRouter({
+  children,
+  initialEntries = ['/en/'],
+  initialIndex = 0
+}: TestRouterProps) {
+  return (
+    <MemoryRouter
+      data-testid="TestRouter"
+      initialEntries={initialEntries}
+      initialIndex={initialIndex}
+    >
+      {children}
+    </MemoryRouter>
+  );
+}

package/dist/templates/react-app/__tests__/__mocks__/components/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Test Components - Reusable test wrappers
+ *
+ * These components provide common test infrastructure:
+ * - TestRouter: Provides React Router context
+ * - TestBootstrapsProvider: Provides IOC context + Router
+ * - TestApp: Complete test wrapper (IOC + Router)
+ */
+
+export { TestRouter } from './TestRouter';
+export { TestBootstrapsProvider } from './TestBootstrapsProvider';
+export { TestApp } from './TestApp';

package/dist/templates/react-app/__tests__/__mocks__/createMockGlobals.ts

@@ -1,7 +1,7 @@
 import { vi } from 'vitest';
-import { MockLogger } from './MockLogger';
 import { MockAppConfig } from './MockAppConfit';
 import { MockDialogHandler } from './MockDialogHandler';
+import { MockLogger } from './MockLogger';
 
 export function createMockGlobals() {
   const mockLogger = new MockLogger();
@@ -16,7 +16,6 @@ export function createMockGlobals() {
     parse: vi.fn((data) => JSON.parse(data))
   };
 
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const storageOptions: Record<string, any> = {
     localStorage: {},
     cookieStorage: {},

package/dist/templates/react-app/__tests__/__mocks__/testIOC/TestIOC.ts

@@ -0,0 +1,51 @@
+import { createIOCFunction } from '@qlover/corekit-bridge';
+import { InversifyContainer } from '@/base/cases/InversifyContainer';
+import type {
+  IOCInterface,
+  IocRegisterOptions
+} from '@/base/port/IOCInterface';
+import type { IOCIdentifierMap } from '@config/IOCIdentifier';
+import { TestIOCRegister } from './TestIOCRegister';
+import type {
+  IOCContainerInterface,
+  IOCFunctionInterface
+} from '@qlover/corekit-bridge';
+
+export class TestIOC
+  implements IOCInterface<IOCIdentifierMap, IOCContainerInterface>
+{
+  protected ioc: IOCFunctionInterface<
+    IOCIdentifierMap,
+    IOCContainerInterface
+  > | null = null;
+
+  getIoc(): IOCFunctionInterface<
+    IOCIdentifierMap,
+    IOCContainerInterface
+  > | null {
+    return this.ioc;
+  }
+
+  create(
+    options: IocRegisterOptions
+  ): IOCFunctionInterface<IOCIdentifierMap, IOCContainerInterface> {
+    if (this.ioc) {
+      return this.ioc;
+    }
+
+    this.ioc = createIOCFunction<IOCIdentifierMap>(new InversifyContainer());
+
+    // move to BootstrapClient
+    const register = new TestIOCRegister(options);
+    // const register = new ClientIOCRegister({
+    //   pathname: '/en/test',
+    //   appConfig: appConfig
+    // });
+
+    register.register(this.ioc.implemention!, this.ioc);
+
+    return this.ioc;
+  }
+}
+
+export const testIOC = new TestIOC();

package/dist/templates/react-app/__tests__/__mocks__/testIOC/TestIOCRegister.ts

@@ -0,0 +1,69 @@
+import { baseNoLocaleRoutes, baseRoutes } from '@config/app.router';
+import { useLocaleRoutes } from '@config/common';
+import { I } from '@config/IOCIdentifier';
+import { themeConfig } from '@config/theme';
+import { ThemeService } from '@qlover/corekit-bridge';
+import type { IocRegisterOptions } from '@/base/port/IOCInterface';
+import { I18nService } from '@/base/services/I18nService';
+import { RouteService } from '@/base/services/RouteService';
+import * as globals from '@/core/globals';
+import { NavigateBridge } from '@/uikit/bridges/NavigateBridge';
+import type {
+  IOCContainerInterface,
+  IOCManagerInterface,
+  IOCRegisterInterface,
+  ThemeServiceProps
+} from '@qlover/corekit-bridge';
+
+/**
+ * TestIOCRegister - Register mock services for testing
+ */
+export class TestIOCRegister
+  implements IOCRegisterInterface<IOCContainerInterface, IocRegisterOptions>
+{
+  constructor(protected options: IocRegisterOptions) {}
+
+  protected registerGlobals(ioc: IOCContainerInterface): void {
+    const { appConfig, dialogHandler, localStorageEncrypt, JSON, logger } =
+      globals;
+
+    ioc.bind(I.JSONSerializer, JSON);
+    ioc.bind(I.Logger, logger);
+    ioc.bind(I.AppConfig, appConfig);
+    ioc.bind(I.EnvConfigInterface, appConfig);
+    ioc.bind(I.DialogHandler, dialogHandler);
+    ioc.bind(I.UIDialogInterface, dialogHandler);
+    ioc.bind(I.AntdStaticApiInterface, dialogHandler);
+    ioc.bind(I.LocalStorage, globals.localStorage);
+    ioc.bind(I.LocalStorageEncrypt, localStorageEncrypt);
+    ioc.bind(I.CookieStorage, globals.cookieStorage);
+  }
+
+  register(
+    ioc: IOCContainerInterface,
+    _manager: IOCManagerInterface<IOCContainerInterface>
+  ): void {
+    this.registerGlobals(ioc);
+
+    ioc.bind(I.I18nServiceInterface, new I18nService(this.options.pathname));
+    ioc.bind(
+      I.RouteServiceInterface,
+      new RouteService(
+        ioc.get(NavigateBridge),
+        ioc.get(I.I18nServiceInterface),
+        {
+          routes: useLocaleRoutes ? baseRoutes : baseNoLocaleRoutes,
+          logger: ioc.get(I.Logger),
+          hasLocalRoutes: useLocaleRoutes
+        }
+      )
+    );
+    ioc.bind(
+      I.ThemeService,
+      new ThemeService({
+        ...(themeConfig as unknown as ThemeServiceProps),
+        storage: ioc.get(I.LocalStorage)
+      })
+    );
+  }
+}