feat: Add test plan

.github/copilot-instructions.md

@@ -4,10 +4,24 @@ VitNode is a comprehensive framework designed to simplify and accelerate applica
 
 > **Important:** VitNode is ESM-only (ECMAScript Modules)
 
-## Frontend Development Guidelines
+## General Guidelines
+
+### Architecture
+
+- TypeScript 5 & React 19
+- ESM (ECMAScript Modules) only
+- pnpm for package management
+- Turborepo for monorepo management
+- Respect Prettier (.prettierrc.mjs)
+- Respect ESLint (each workspace has eslint.config.mjs) for code formatting and linting
+- Respect Typescript rules (each workspace has tsconfig.json)
+- Don't use deprecated or outdated features
+- Use objects instead of enums in TypeScript
 
 ### Core Technologies
 
+**Frontend:**
+
 - **Framework:** Next.js 15
 - **Styling:** Tailwind CSS 4
 - **UI Components:** Shadcn UI
@@ -16,15 +30,41 @@ VitNode is a comprehensive framework designed to simplify and accelerate applica
 - **Schema Validation:** zod 3
 - **Form Handling:** react-hook-form 7
 
+**Backend:**
+
+- **Framework**: Hono.js
+- **RPC**: Type-safe API calls
+- **Documentation**: Fumadocs & Swagger 3
+- **Schema validation**: zod 3 & @hono/zod-openapi
+
+### Documentation
+
+- **Framework**: Fumadocs
+- Use easy and clear language for documentation to make it accessible to a wide audience
+- Use clear and concise examples to illustrate concepts
+- Use `// [!code ++]` to highlight code snippets and `// [!code --]` to hide code snippets
+
+### Project Structure
+
+The code is organized into two main directories:
+
+- `apps/web/` - the main frontend application,
+  - `apps/web/src/app/[locale]/(main)` - the main application code,
+  - `apps/web/src/app/[locale]/admin` - the admin panel code,
+- `apps/docs/` - the documentation application
+- `packages/vitnode` - the core of the framework, which is used by the `web` application
+
+## FRONTEND
+
 ### Architecture Requirements
 
 - Use App Router and Server Components for improved performance and SEO
 - Use server actions for form handling and data mutations from Server Components
 - Leverage Next.js Image component with proper sizing for core web vitals optimization
 - Implement the Metadata API for dynamic SEO optimization
-- Use React Server Components for {{data_fetching_operations}} to reduce client-side JavaScript
+- Use React Server Components for data fetching operations to reduce client-side JavaScript
 - Implement Streaming and Suspense for improved loading states
-- Use the new Link component without requiring a child <a> tag
+- Use the new Link component without requiring a child `<a>` tag
 - Leverage parallel routes for complex layouts and parallel data fetching
 - Implement intercepting routes for modal patterns and nested UIs
 - Navigation api is in `vitnode/lib/navigation` file. Avoid using `next/navigation` directly
@@ -36,83 +76,32 @@ VitNode is a comprehensive framework designed to simplify and accelerate applica
 - Languages keys should be added in `apps/web/src/plugins/core/langs/{lang_key}.ts` file
 - Use `getTranslation` function for server component but `useTranslation` for client
 
-## Documentation
-
-- **Framework**: Fumadocs
-- Use easy and clear language for documentation to make it accessible to a wide audience
-- Use clear and concise examples to illustrate concepts
-- Use `// [!code ++]` to highlight code snippets and `// [!code --]` to hide code snippets
-
-### Component Paths
-
-#### Shadcn UI components
-
-| Component     | Path for `apps/web/`                  | Path for `packages/vitnode`     |
-| ------------- | ------------------------------------- | ------------------------------- |
-| Alert         | `vitnode/components/ui/alert`         | `@/components/ui/alert`         |
-| Button        | `vitnode/components/ui/button`        | `@/components/ui/button`        |
-| Card          | `vitnode/components/ui/card`          | `@/components/ui/card`          |
-| Checkbox      | `vitnode/components/ui/checkbox`      | `@/components/ui/checkbox`      |
-| Drawer        | `vitnode/components/ui/drawer`        | `@/components/ui/drawer`        |
-| Dropdown Menu | `vitnode/components/ui/dropdown-menu` | `@/components/ui/dropdown-menu` |
-| Form          | `vitnode/components/ui/form`          | `@/components/ui/form`          |
-| Input         | `vitnode/components/ui/input`         | `@/components/ui/input`         |
-| Label         | `vitnode/components/ui/label`         | `@/components/ui/label`         |
-| Separator     | `vitnode/components/ui/separator`     | `@/components/ui/separator`     |
-| Sheet         | `vitnode/components/ui/sheet`         | `@/components/ui/sheet`         |
-| Skeleton      | `vitnode/components/ui/skeleton`      | `@/components/ui/skeleton`      |
-| Sonner        | `vitnode/components/ui/sonner`        | `@/components/ui/sonner`        |
-| Tooltip       | `vitnode/components/ui/tooltip`       | `@/components/ui/tooltip`       |
-| Collapsible   | `vitnode/components/ui/collapsible`   | `@/components/ui/collapsible`   |
-
-#### Other UI components
-
-| Component | Path for `apps/web/`           | Path for `packages/vitnode` |
-| --------- | ------------------------------ | --------------------------- |
-| Loader    | `vitnode/components/ui/loader` | `@/components/ui/loader`    |
+## BACKEND
 
-#### Other components
-
-| Component    | Path for `apps/web/`              | Path for `packages/vitnode` |
-| ------------ | --------------------------------- | --------------------------- |
-| Avatar       | `vitnode/components/avatar`       | `@/components/avatar`       |
-| Logo Vitnode | `vitnode/components/logo-vitnode` | `@/components/logo-vitnode` |
-
-## Backend
-
-- **Framework**: Hono.js
-- **RPC**: Type-safe API calls
-- **Documentation**: Fumadocs & Swagger 3
-- **Schema validation**: zod 3 & @hono/zod-openapi
+### Development Guidelines
 
 - Write backend code in `packages/vitnode/src/api` directory
 - Generate OpenAPI documentation using `@hono/zod-openapi` for all API endpoints
 
-## Database
+### Database
 
 - Use `PostgreSQL` with `Drizzle ORM`
 - Use UUIDs for all database IDs
 - You can find the database schema in the `apps/web/src/database/schema` files
 - Respect performance and security best practices when designing the database schema
 
-## Architecture
-
-- TypeScript 5 & React 19
-- ESM (ECMAScript Modules) only
-- pnpm for package management
-- Turborepo for monorepo management
-- Respect Prettier (.prettierrc.mjs)
-- Respect ESLint (each workspace has eslint.config.mjs) for code formatting and linting
-- Respect Typescript rules (each workspace has tsconfig.json)
-- Don't use deprecated or outdated features
-- Use objects instead of enums in TypeScript
-
-## Project Structure
-
-The code is organized into two main directories:
-
-- `apps/web/` - the main frontend application,
-  - `apps/web/src/app/[locale]/(main)` - the main application code,
-  - `apps/web/src/app/[locale]/admin` - the admin panel code,
-- `apps/docs/` - the documentation application
-- `packages/vitnode` - the core of the framework, which is used by the `web` application
+## TESTING
+
+### VITEST
+
+- Leverage the `vi` object for test doubles - Use `vi.fn()` for function mocks, `vi.spyOn()` to monitor existing functions, and `vi.stubGlobal()` for global mocks. Prefer spies over mocks when you only need to verify interactions without changing behavior.
+- Master `vi.mock()` factory patterns - Place mock factory functions at the top level of your test file, return typed mock implementations, and use `mockImplementation()` or `mockReturnValue()` for dynamic control during tests. Remember the factory runs before imports are processed.
+- Create setup files for reusable configuration - Define global mocks, custom matchers, and environment setup in dedicated files referenced in your `vitest.config.ts`. This keeps your test files clean while ensuring consistent test environments.
+- Use inline snapshots for readable assertions - Replace complex equality checks with `expect(value).toMatchInlineSnapshot()` to capture expected output directly in your test file, making changes more visible in code reviews.
+- Monitor coverage with purpose and only when asked - Configure coverage thresholds in `vitest.config.ts` to ensure critical code paths are tested, but focus on meaningful tests rather than arbitrary coverage percentages.
+- Make watch mode part of your workflow - Run `vitest --watch` during development for instant feedback as you modify code, filtering tests with `-t` to focus on specific areas under development.
+- Explore UI mode for complex test suites - Use `vitest --ui` to visually navigate large test suites, inspect test results, and debug failures more efficiently during development.
+- Handle optional dependencies with smart mocking - Use conditional mocking to test code with optional dependencies by implementing `vi.mock()` with the factory pattern for modules that might not be available in all environments.
+- Configure jsdom for DOM testing - Set `environment: 'jsdom'` in your configuration for frontend component tests and combine with testing-library utilities for realistic user interaction simulation.
+- Structure tests for maintainability - Group related tests with descriptive `describe` blocks, use explicit assertion messages, and follow the Arrange-Act-Assert pattern to make tests self-documenting.
+- Leverage TypeScript type checking in tests - Enable strict typing in your tests to catch type errors early, use `expectTypeOf()` for type-level assertions, and ensure mocks preserve the original type signatures.

.github/docs/tests_plan.md

@@ -0,0 +1,101 @@
+# VitNode Test Plan
+
+## 1. Introduction
+
+This document outlines the testing strategy for the VitNode framework. The goal is to ensure the reliability, functionality, and performance of the core framework (`packages/vitnode`), the web application (`apps/web`), and associated plugins. We will utilize Vitest for unit and integration testing and Playwright for end-to-end testing.
+
+## 2. Goals
+
+- Ensure core framework features function as expected ([.github/docs/prd.md](.github/docs/prd.md)).
+- Verify the stability and correctness of the AdminCP and user-facing application.
+- Validate authentication (credentials, SSO: Google, GitHub, Facebook), authorization, and permission systems.
+- Confirm database interactions and schema integrity.
+- Ensure the plugin system allows for seamless extension of functionality (new pages, API endpoints, AdminCP pages, SSO providers, email providers).
+- Maintain high code quality and prevent regressions.
+- Achieve performance and accessibility targets ([.github/docs/prd.md](.github/docs/prd.md)).
+
+## 3. Testing Tools
+
+- **[Vitest](https://vitest.dev/):** For unit and integration tests. Chosen for its speed, ESM support, and compatibility with the Vite ecosystem (used by Next.js) and Hono.js.
+- **[Playwright](https://playwright.dev/):** For end-to-end tests. Chosen for its cross-browser capabilities, reliability, and features like auto-waits and tracing.
+
+## 4. Types of Tests
+
+### 4.1. Unit Tests (Vitest)
+
+**Scope:** Test individual functions, components, and utilities in isolation.
+**Location:** Primarily within `packages/vitnode` and utility directories in `apps/web`.
+
+**Areas to Cover:**
+
+- **Core Utilities:** Functions in `packages/vitnode/src/lib`, helpers, etc.
+- **API Helpers:** Route building, validation logic using `@hono/zod-openapi`.
+- **UI Components:** Basic rendering tests, prop validation for components in `packages/vitnode/src/components` and `apps/web/src/components`.
+- **Configuration Loading:** Ensure `vitnode.config.ts` is loaded and parsed correctly.
+- **Internationalization (i18n):** Test translation loading and formatting utilities.
+
+### 4.2. Integration Tests (Vitest)
+
+**Scope:** Test the interaction between different modules or layers of the application.
+**Location:** Test files adjacent to the features they cover (e.g., API routes, server actions).
+
+**Areas to Cover:**
+
+- **API Endpoints:** Test request handling, validation, middleware execution, and response generation for Hono.js routes defined in `packages/vitnode/src/api`. Example: [`testRoute`](packages/vitnode/src/api/modules/users/routes/test.route.ts).
+- **Server Actions:** Test form submissions, data mutations, and interactions with the database within `apps/web`.
+- **Database Interactions:** Verify Drizzle ORM queries, schema interactions, and data integrity (using a test database).
+- **Authentication Logic:** Test credential verification, session creation/validation (including durations), email verification, password reset, and SSO provider interactions (Google, GitHub, Facebook).
+- **Plugin Integration:** Test how core systems interact with plugin-provided extensions (routes, hooks, etc.).
+
+### 4.3. End-to-End Tests (Playwright)
+
+**Scope:** Simulate real user scenarios by interacting with the application through a browser.
+**Location:** A dedicated `e2e` or `tests` directory at the root or within `apps/web`.
+
+**Areas to Cover:**
+
+- **Authentication Flows:**
+  - User registration
+  - Login with credentials
+  - Login with SSO providers (Google, GitHub, Facebook - as defined in [.github/docs/prd.md](.github/docs/prd.md))
+  - Password reset flow
+  - Email verification flow
+  - Logout
+- **AdminCP Functionality:**
+  - Navigating the AdminCP interface
+  - User Management: Create, Read, Update, Delete (CRUD) users, search, filter ([.github/docs/prd.md](.github/docs/prd.md))
+  - Role Management: CRUD roles and assign permissions ([.github/docs/prd.md](.github/docs/prd.md))
+  - Plugin Management (if applicable)
+  - Viewing system settings/information
+- **Main Application Flows:**
+  - Navigating public pages
+  - User profile updates (password, email, avatar)
+  - Content interaction (e.g., viewing blog posts if `plugins/blog` is enabled)
+- **Plugin-Specific Flows:** E2E tests for critical user journeys introduced by plugins.
+- **Responsiveness:** Basic checks across different viewport sizes.
+- **Accessibility:** Automated accessibility checks using Playwright's integrations to meet WCAG 2.1 guidelines.
+
+## 5. Test Environment
+
+- **Database:** A separate PostgreSQL database instance for testing, managed via Docker ([docker-compose.yml](docker-compose.yml)). Schema pushed using `pnpm db:push`.
+- **Environment Variables:** A specific `.env.test` file or equivalent mechanism for test-specific configurations (e.g., database connection strings, API keys for test accounts).
+- **Seeding:** Scripts to seed the test database with necessary initial data (roles, languages, default users, permissions, etc.) before test runs.
+
+## 6. Running Tests
+
+- **Unit/Integration:** `pnpm test` or specific Vitest commands targeting files/directories. (Note: `README.md` lists `pnpm test` but not specific unit/integration scripts yet).
+- **End-to-End:** `pnpm test:e2e` (script to be defined). Playwright command to run the E2E test suite.
+- **All Tests:** `pnpm test` (script to be defined, potentially running both Vitest and Playwright suites).
+
+## 7. CI/CD Integration
+
+- Tests will be automatically executed on pull requests and pushes to the main branch using GitHub Actions ([.github/workflows/](.github/workflows/)).
+- Test results and coverage reports will be generated and made available.
+- Failing tests will block merging/deployment as per CI/CD configuration ([.github/docs/prd.md](.github/docs/prd.md)).
+- CI/CD pipeline includes linting, formatting, security scanning, build checks, and potentially deployment steps.
+
+## 8. Reporting
+
+- Test results will be reported in the CI/CD pipeline output.
+- Code coverage reports will be generated (using Vitest's coverage capabilities) and potentially uploaded as artifacts or integrated with services like Codecov.
+- Playwright reports (HTML, traces) will be generated for E2E test runs, especially for failures, to aid debugging.

.github/workflows/build-lint-test.yml

@@ -0,0 +1,100 @@
+name: Build, Lint & Test
+
+on:
+  pull_request:
+    branches: '*'
+    types:
+      - opened
+      - edited
+      - synchronize
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      - uses: pnpm/action-setup@v4
+        name: Install pnpm
+        with:
+          version: 10.10.0
+
+      - name: Install Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build Scripts
+        run: pnpm build:scripts
+
+      # - name: Build Packages
+      #   run: pnpm build:packages
+
+      # - name: Run config init
+      #   run: pnpm config:init:skip-database
+
+      - name: Run build
+        run: pnpm build
+
+  lint:
+    runs-on: ubuntu-latest
+    needs: build
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      - uses: pnpm/action-setup@v4
+        name: Install pnpm
+        with:
+          version: 10.10.0
+
+      - name: Install Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Check formatting
+        run: pnpm lint
+
+  test:
+    runs-on: ubuntu-latest
+    needs: build
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      - uses: pnpm/action-setup@v4
+        name: Install pnpm
+        with:
+          version: 10.10.0
+
+      - name: Install Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Run tests
+        run: pnpm test