@qlover/create-app 0.10.5 → 0.11.0

package/dist/templates/react-app/docs/en/test-guide.md

@@ -627,7 +627,20 @@ describe('AsyncService', () => {
 
 ### Type Safety Testing
 
+TypeScript project tests should not only verify runtime behavior but also ensure the correctness of the type system. Vitest provides the `expectTypeOf` utility for compile-time type checking.
+
+#### Why Type Testing?
+
+1. **Type Inference Validation**: Ensure TypeScript correctly infers complex types
+2. **Generic Constraint Checking**: Verify generic parameter constraints
+3. **Type Compatibility**: Ensure type definitions match actual usage
+4. **API Contract Guarantee**: Prevent breaking changes in type definitions
+
+#### Basic Type Testing
+
 ```typescript
+import { describe, it, expectTypeOf } from 'vitest';
+
 describe('TypeSafetyTests', () => {
   it('should maintain type safety', () => {
     const processor = new DataProcessor<User>();
@@ -636,9 +649,190 @@ describe('TypeSafetyTests', () => {
     expectTypeOf(processor.process).parameter(0).toEqualTypeOf<User>();
     expectTypeOf(processor.process).returns.toEqualTypeOf<ProcessedUser>();
   });
+
+  it('should infer correct return types', () => {
+    const result = getData();
+    
+    // Verify return type
+    expectTypeOf(result).toEqualTypeOf<{ id: number; name: string }>();
+    expectTypeOf(result).not.toEqualTypeOf<{ id: string; name: string }>();
+  });
+
+  it('should validate parameter types', () => {
+    function processUser(user: User): void {
+      // implementation
+    }
+
+    // Verify parameter type
+    expectTypeOf(processUser).parameter(0).toMatchTypeOf<{ id: number }>();
+    expectTypeOf(processUser).parameter(0).toHaveProperty('id');
+  });
+});
+```
+
+#### Generic Type Testing
+
+```typescript
+describe('Generic Type Tests', () => {
+  it('should work with generic constraints', () => {
+    class Storage<T extends { id: number }> {
+      store(item: T): T {
+        return item;
+      }
+    }
+
+    const storage = new Storage<User>();
+    
+    // Verify generic type
+    expectTypeOf(storage.store).parameter(0).toMatchTypeOf<User>();
+    expectTypeOf(storage.store).returns.toMatchTypeOf<User>();
+  });
+
+  it('should validate complex generic types', () => {
+    type ApiResponse<T> = {
+      data: T;
+      status: number;
+      message?: string;
+    };
+
+    const response: ApiResponse<User[]> = {
+      data: [],
+      status: 200
+    };
+
+    // Verify nested generic type
+    expectTypeOf(response).toMatchTypeOf<ApiResponse<User[]>>();
+    expectTypeOf(response.data).toEqualTypeOf<User[]>();
+  });
+});
+```
+
+#### Union and Intersection Type Testing
+
+```typescript
+describe('Union and Intersection Types', () => {
+  it('should handle union types correctly', () => {
+    type Result = Success | Error;
+    type Success = { status: 'success'; data: string };
+    type Error = { status: 'error'; message: string };
+
+    function handleResult(result: Result): void {
+      // implementation
+    }
+
+    // Verify union type
+    expectTypeOf(handleResult).parameter(0).toMatchTypeOf<Success>();
+    expectTypeOf(handleResult).parameter(0).toMatchTypeOf<Error>();
+  });
+
+  it('should handle intersection types correctly', () => {
+    type Timestamped = { createdAt: Date; updatedAt: Date };
+    type UserWithTimestamp = User & Timestamped;
+
+    const user: UserWithTimestamp = {
+      id: 1,
+      name: 'John',
+      createdAt: new Date(),
+      updatedAt: new Date()
+    };
+
+    // Verify intersection type contains all properties
+    expectTypeOf(user).toHaveProperty('id');
+    expectTypeOf(user).toHaveProperty('name');
+    expectTypeOf(user).toHaveProperty('createdAt');
+    expectTypeOf(user).toHaveProperty('updatedAt');
+  });
 });
 ```
 
+#### Type Narrowing Testing
+
+```typescript
+describe('Type Narrowing Tests', () => {
+  it('should validate type guards', () => {
+    function isString(value: unknown): value is string {
+      return typeof value === 'string';
+    }
+
+    const value: unknown = 'test';
+    
+    if (isString(value)) {
+      // Within this scope, value should be narrowed to string type
+      expectTypeOf(value).toEqualTypeOf<string>();
+    }
+  });
+
+  it('should validate discriminated unions', () => {
+    type Shape = 
+      | { kind: 'circle'; radius: number }
+      | { kind: 'rectangle'; width: number; height: number };
+
+    function getArea(shape: Shape): number {
+      if (shape.kind === 'circle') {
+        // In this branch, shape should be narrowed to circle type
+        expectTypeOf(shape).toHaveProperty('radius');
+        expectTypeOf(shape).not.toHaveProperty('width');
+        return Math.PI * shape.radius ** 2;
+      } else {
+        // In this branch, shape should be narrowed to rectangle type
+        expectTypeOf(shape).toHaveProperty('width');
+        expectTypeOf(shape).toHaveProperty('height');
+        return shape.width * shape.height;
+      }
+    }
+  });
+});
+```
+
+#### Practical Recommendations
+
+1. **Combine with Runtime Tests**: Type tests should complement runtime tests
+
+```typescript
+describe('Combined Runtime and Type Tests', () => {
+  it('should validate both runtime behavior and types', () => {
+    function add(a: number, b: number): number {
+      return a + b;
+    }
+
+    // Type test
+    expectTypeOf(add).parameter(0).toEqualTypeOf<number>();
+    expectTypeOf(add).returns.toEqualTypeOf<number>();
+
+    // Runtime test
+    expect(add(1, 2)).toBe(3);
+    expect(add(-1, 1)).toBe(0);
+  });
+});
+```
+
+2. **Test Type Inference**: Ensure TypeScript correctly infers types, avoid overusing `any`
+
+```typescript
+describe('Type Inference Tests', () => {
+  it('should infer types correctly', () => {
+    const data = { id: 1, name: 'John' };
+    
+    // Verify inferred type
+    expectTypeOf(data).toEqualTypeOf<{ id: number; name: string }>();
+    expectTypeOf(data.id).toEqualTypeOf<number>();
+    expectTypeOf(data.name).toEqualTypeOf<string>();
+  });
+});
+```
+
+3. **Use TypeScript Compiler Checks**: Run `tsc --noEmit` in CI to ensure no type errors
+
+```bash
+# Add script in package.json
+{
+  "scripts": {
+    "type-check": "tsc --noEmit",
+    "test": "pnpm type-check && vitest run"
+  }
+}
+```
+
 ---
 
 ## Performance Testing

package/dist/templates/react-app/docs/zh/test-guide.md

@@ -627,7 +627,20 @@ describe('AsyncService', () => {
 
 ### 类型安全测试
 
+TypeScript 项目的测试不仅要验证运行时行为，还应该确保类型系统的正确性。Vitest 提供了 `expectTypeOf` 工具来进行编译时类型检查。
+
+#### 为什么需要类型测试？
+
+1. **类型推断验证**：确保 TypeScript 能正确推断复杂类型
+2. **泛型约束检查**：验证泛型参数的约束条件
+3. **类型兼容性**：确保类型定义与实际使用匹配
+4. **API 契约保证**：防止类型定义的破坏性变更
+
+#### 基础类型测试
+
 ```typescript
+import { describe, it, expectTypeOf } from 'vitest';
+
 describe('TypeSafetyTests', () => {
   it('should maintain type safety', () => {
     const processor = new DataProcessor<User>();
@@ -636,9 +649,190 @@ describe('TypeSafetyTests', () => {
     expectTypeOf(processor.process).parameter(0).toEqualTypeOf<User>();
     expectTypeOf(processor.process).returns.toEqualTypeOf<ProcessedUser>();
   });
+
+  it('should infer correct return types', () => {
+    const result = getData();
+    
+    // 验证返回值类型
+    expectTypeOf(result).toEqualTypeOf<{ id: number; name: string }>();
+    expectTypeOf(result).not.toEqualTypeOf<{ id: string; name: string }>();
+  });
+
+  it('should validate parameter types', () => {
+    function processUser(user: User): void {
+      // implementation
+    }
+
+    // 验证参数类型
+    expectTypeOf(processUser).parameter(0).toMatchTypeOf<{ id: number }>();
+    expectTypeOf(processUser).parameter(0).toHaveProperty('id');
+  });
+});
+```
+
+#### 泛型类型测试
+
+```typescript
+describe('Generic Type Tests', () => {
+  it('should work with generic constraints', () => {
+    class Storage<T extends { id: number }> {
+      store(item: T): T {
+        return item;
+      }
+    }
+
+    const storage = new Storage<User>();
+    
+    // 验证泛型类型
+    expectTypeOf(storage.store).parameter(0).toMatchTypeOf<User>();
+    expectTypeOf(storage.store).returns.toMatchTypeOf<User>();
+  });
+
+  it('should validate complex generic types', () => {
+    type ApiResponse<T> = {
+      data: T;
+      status: number;
+      message?: string;
+    };
+
+    const response: ApiResponse<User[]> = {
+      data: [],
+      status: 200
+    };
+
+    // 验证嵌套泛型类型
+    expectTypeOf(response).toMatchTypeOf<ApiResponse<User[]>>();
+    expectTypeOf(response.data).toEqualTypeOf<User[]>();
+  });
+});
+```
+
+#### 联合类型与交叉类型测试
+
+```typescript
+describe('Union and Intersection Types', () => {
+  it('should handle union types correctly', () => {
+    type Result = Success | Error;
+    type Success = { status: 'success'; data: string };
+    type Error = { status: 'error'; message: string };
+
+    function handleResult(result: Result): void {
+      // implementation
+    }
+
+    // 验证联合类型
+    expectTypeOf(handleResult).parameter(0).toMatchTypeOf<Success>();
+    expectTypeOf(handleResult).parameter(0).toMatchTypeOf<Error>();
+  });
+
+  it('should handle intersection types correctly', () => {
+    type Timestamped = { createdAt: Date; updatedAt: Date };
+    type UserWithTimestamp = User & Timestamped;
+
+    const user: UserWithTimestamp = {
+      id: 1,
+      name: 'John',
+      createdAt: new Date(),
+      updatedAt: new Date()
+    };
+
+    // 验证交叉类型包含所有属性
+    expectTypeOf(user).toHaveProperty('id');
+    expectTypeOf(user).toHaveProperty('name');
+    expectTypeOf(user).toHaveProperty('createdAt');
+    expectTypeOf(user).toHaveProperty('updatedAt');
+  });
 });
 ```
 
+#### 类型窄化测试
+
+```typescript
+describe('Type Narrowing Tests', () => {
+  it('should validate type guards', () => {
+    function isString(value: unknown): value is string {
+      return typeof value === 'string';
+    }
+
+    const value: unknown = 'test';
+    
+    if (isString(value)) {
+      // 在此作用域内，value 应该被窄化为 string 类型
+      expectTypeOf(value).toEqualTypeOf<string>();
+    }
+  });
+
+  it('should validate discriminated unions', () => {
+    type Shape = 
+      | { kind: 'circle'; radius: number }
+      | { kind: 'rectangle'; width: number; height: number };
+
+    function getArea(shape: Shape): number {
+      if (shape.kind === 'circle') {
+        // 在此分支，shape 应该被窄化为 circle 类型
+        expectTypeOf(shape).toHaveProperty('radius');
+        expectTypeOf(shape).not.toHaveProperty('width');
+        return Math.PI * shape.radius ** 2;
+      } else {
+        // 在此分支，shape 应该被窄化为 rectangle 类型
+        expectTypeOf(shape).toHaveProperty('width');
+        expectTypeOf(shape).toHaveProperty('height');
+        return shape.width * shape.height;
+      }
+    }
+  });
+});
+```
+
+#### 实用建议
+
+1. **结合运行时测试**：类型测试应该与运行时测试相辅相成
+
+```typescript
+describe('Combined Runtime and Type Tests', () => {
+  it('should validate both runtime behavior and types', () => {
+    function add(a: number, b: number): number {
+      return a + b;
+    }
+
+    // 类型测试
+    expectTypeOf(add).parameter(0).toEqualTypeOf<number>();
+    expectTypeOf(add).returns.toEqualTypeOf<number>();
+
+    // 运行时测试
+    expect(add(1, 2)).toBe(3);
+    expect(add(-1, 1)).toBe(0);
+  });
+});
+```
+
+2. **测试类型推断**：确保 TypeScript 能正确推断类型，避免过度使用 `any`
+
+```typescript
+describe('Type Inference Tests', () => {
+  it('should infer types correctly', () => {
+    const data = { id: 1, name: 'John' };
+    
+    // 验证推断的类型
+    expectTypeOf(data).toEqualTypeOf<{ id: number; name: string }>();
+    expectTypeOf(data.id).toEqualTypeOf<number>();
+    expectTypeOf(data.name).toEqualTypeOf<string>();
+  });
+});
+```
+
+3. **使用 TypeScript 编译器检查**：在 CI 中运行 `tsc --noEmit` 确保没有类型错误
+
+```bash
+# 在 package.json 中添加脚本
+{
+  "scripts": {
+    "type-check": "tsc --noEmit",
+    "test": "pnpm type-check && vitest run"
+  }
+}
+```
+
 ---
 
 ## 性能测试

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qlover/create-app",
-  "version": "0.10.5",
+  "version": "0.11.0",
   "description": "Create a new app with a single command",
   "private": false,
   "type": "module",