cgoinglove
diff --git a/‎.github/workflows/e2e-tests.yml‎
Lines changed: 8 additions & 5 deletions b/‎.github/workflows/e2e-tests.yml‎
Lines changed: 8 additions & 5 deletions
diff --git a/‎.gitignore‎
Lines changed: 1 addition & 1 deletion b/‎.gitignore‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎CONTRIBUTING.md‎
Lines changed: 13 additions & 24 deletions b/‎CONTRIBUTING.md‎
Lines changed: 13 additions & 24 deletions
diff --git a/‎README.md‎
Lines changed: 26 additions & 15 deletions b/‎README.md‎
Lines changed: 26 additions & 15 deletions
diff --git a/‎docs/tips-guides/e2e-testing-guide.md‎
Lines changed: 17 additions & 34 deletions b/‎docs/tips-guides/e2e-testing-guide.md‎
Lines changed: 17 additions & 34 deletions
@@ -24,7 +24,7 @@ jobs:
 
       # LLM Provider (OpenRouter with free models)
       OPENROUTER_API_KEY: ${{ secrets.E2E_OPENROUTER_API_KEY || 'test-key' }}
-      E2E_DEFAULT_MODEL: openRouter/moonshotai/kimi-k2:free
+      E2E_DEFAULT_MODEL: openRouter/gemini-2.0-flash-exp:free
 
       # Feature flags
       DISABLE_SIGN_UP: 0
@@ -83,7 +83,10 @@ jobs:
           touch .env
 
       - name: Run database migrations
-        run: pnpm db:push
+        run: pnpm db:migrate
+
+      - name: Seed test users once before all tests
+        run: pnpm test:e2e:seed
 
       - name: Build application
         run: pnpm build:local
@@ -92,8 +95,8 @@ jobs:
         run: pnpm test:e2e
 
       - uses: actions/upload-artifact@v4
-        if: ${{ !cancelled() }}
+        if: always()
         with:
-          name: test-results
-          path: test-results/
+          name: playwright-report
+          path: playwright-report/
           retention-days: 30
@@ -58,4 +58,4 @@ local-data
 *.ignore
 .mcp-config.json
 openai-compatible.config.ts
-certificates
+certificates
@@ -67,34 +67,23 @@ If you are fixing a bug, please add tests to prevent the same bug from happening
 
 6. **Run e2e tests**:
 
-Before opening a PR run e2e tests to ensure your changes work as expected.
-
-```bash
-
-# install playwright browsers - you only need to do this once
-pnpm playwright:install # install playwright browsers
-
-# this is typically the command you will use to run all e2e tests
-pnpm test:e2e # run all e2e tests
-```
-
-To help you debug, you can run the tests individually or in headed mode to see the browser UI.
-
-```bash
+   ```bash
+   pnpm playwright:install # install playwright browsers
+   pnpm test:e2e # run all e2e tests (48 tests covering core functionality)
 
-# Optional: run specific test suites in a folder
-pnpm test:e2e -- tests/agents/
-pnpm test:e2e -- tests/models/
+   # Optional: run specific test suites
+   pnpm test:e2e -- tests/agents/
+   pnpm test:e2e -- tests/models/
 
-# Debug specific test file in headed mode to see the browser UI
-pnpm test:e2e -- tests/agents/agent-visibility.spec.ts --headed
-```
+   # Debug specific test
+   pnpm test:e2e -- tests/agents/agent-visibility.spec.ts --headed
+   ```
 
-**E2E Test Requirements:**
+   **E2E Test Requirements:**
 
-- PostgreSQL database (use `pnpm docker:pg` for quick setup)
-- At least one LLM provider API key (OpenAI, Anthropic, or Google)
-- `BETTER_AUTH_SECRET` environment variable set
+   - PostgreSQL database (use `pnpm docker:pg` for quick setup)
+   - At least one LLM provider API key (OpenAI, Anthropic, or Google)
+   - `BETTER_AUTH_SECRET` environment variable set
 
 ---
 
 
@@ -1,6 +1,5 @@
 <img width="1184" height="576" alt="thumbnail" loading="lazy" src="https://github.com/user-attachments/assets/d6ba80ff-a62a-4920-b266-85c4a89d6076" />
 
-
 [![MCP Supported](https://img.shields.io/badge/MCP-Supported-00c853)](https://modelcontextprotocol.io/introduction)
 [![Local First](https://img.shields.io/badge/Local-First-blue)](https://localfirstweb.dev/)
 [![Discord](https://img.shields.io/discord/1374047276074537103?label=Discord&logo=discord&color=5865F2)](https://discord.gg/gCRu69Upnp)
@@ -17,11 +16,10 @@
 • **Collaboration** - Share agents, workflows, and MCP configurations with your team  
 • **Voice Assistant** - Realtime voice chat with full MCP tool integration  
 • **Intuitive UX** - Instantly invoke any feature with `@mention`  
-• **Quick Start** - Deploy free with Vercel Deploy button  
+• **Quick Start** - Deploy free with Vercel Deploy button
 
 Built with Vercel AI SDK and Next.js, combining the best features of leading AI services into one platform.
 
-
 ### Quick Start 🚀
 
 ```bash
@@ -80,15 +78,15 @@ Open [http://localhost:3000](http://localhost:3000) in your browser to get start
   - [Quick Start (Local Version) 🚀](#quick-start-local-version-)
   - [Environment Variables](#environment-variables)
 - [📘 Guides](#-guides)
-    - [🔌 MCP Server Setup \& Tool Testing](#-mcp-server-setup--tool-testing)
-    - [🐳 Docker Hosting Guide](#-docker-hosting-guide)
-    - [▲ Vercel Hosting Guide](#-vercel-hosting-guide)
-    - [🎯 System Prompts \& Chat Customization](#-system-prompts--chat-customization)
-    - [🔐 OAuth Sign-In Setup](#-oauth-sign-in-setup)
-    - [🕵🏿 Adding openAI like providers](#-adding-openai-like-providers)
-    - [🧪 E2E Testing Guide](#-e2e-testing-guide)
+  - [🔌 MCP Server Setup \& Tool Testing](#-mcp-server-setup--tool-testing)
+  - [🐳 Docker Hosting Guide](#-docker-hosting-guide)
+  - [▲ Vercel Hosting Guide](#-vercel-hosting-guide)
+  - [🎯 System Prompts \& Chat Customization](#-system-prompts--chat-customization)
+  - [🔐 OAuth Sign-In Setup](#-oauth-sign-in-setup)
+  - [🕵🏿 Adding openAI like providers](#-adding-openai-like-providers)
+  - [🧪 E2E Testing Guide](#-e2e-testing-guide)
 - [💡 Tips](#-tips)
-    - [💬 Temporary Chat Windows](#-temporary-chat-windows)
+  - [💬 Temporary Chat Windows](#-temporary-chat-windows)
 - [🗺️ Roadmap](#️-roadmap)
 - [🙌 Contributing](#-contributing)
 - [💬 Join Our Discord](#-join-our-discord)
@@ -103,7 +101,6 @@ Get a feel for the UX — here's a quick look at what's possible.
 
 ![preview](https://github.com/user-attachments/assets/e4febb04-26d5-45da-a7bb-f7d452d333c2)
 
-
 **Example:** Control a web browser using Microsoft's [playwright-mcp](https://github.com/microsoft/playwright-mcp) tool.
 
 - The LLM autonomously decides how to use tools from the MCP server, calling them multiple times to complete a multi-step task and return a final message.
@@ -144,10 +141,11 @@ Sample prompt:
 **Example:** Create specialized AI agents with custom instructions and tool access.
 
 - Define custom agents with specific system prompts and available tools
-- Easily invoke agents in chat using `@agent_name` 
+- Easily invoke agents in chat using `@agent_name`
 - Build task-specific assistants like a GitHub Manager agent with issue/PR tools and project context
 
 For instance, create a GitHub Manager agent by:
+
 - Providing GitHub tools (issue/PR creation, comments, queries)
 - Adding project details to the system prompt
 - Calling it with `@github_manager` to manage your repository
@@ -277,9 +275,22 @@ pnpm build:local && pnpm start
 # pnpm dev
 ```
 
-Open [http://localhost:3000](http://localhost:3000) in your browser to get started.
+Alternative: Use Docker Compose for DB only (run app via pnpm)
 
-<br/>
+```bash
+# Start Postgres only via compose
+# Ensure your .env includes: POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB matching POSTGRES_URL
+docker compose -f docker/compose.yml up -d postgres
+
+# Apply migrations
+pnpm db:migrate
+
+
+# Run app locally
+pnpm dev   # or: pnpm build && pnpm start
+```
+
+Open [http://localhost:3000](http://localhost:3000) in your browser to get started.
 
 ### Environment Variables
 
 
@@ -21,7 +21,7 @@ pnpm test:e2e:ui
 pnpm test:e2e -- tests/agents/agent-creation.spec.ts
 
 # Run tests in debug mode
-pnpm test:e2e -- --debug
+pnpm test:e2e:debug
 ```
 
 ## 🏗️ Test Architecture
@@ -83,28 +83,17 @@ We recommend using the [Playwright](https://marketplace.visualstudio.com/items?i
 
 ### Test Database
 
-For safety, always use a **separate test, local database**. If you run this against a production database, it can **severely impact your data**.
-
-The easiest database to use the local postgres database setup through the included docker compose file.
-
 ```bash
-# Use Docker (recommended)
 pnpm docker:pg
 ```
 
-Set the `POSTGRES_URL` environment variable in your .env to the test database URL.
-
-```text
-POSTGRES_URL="postgres://user:password@localhost:5432/better_chatbot"
-```
-
 ## 🎯 Authentication Strategy
 
 ### Authentication Setup
 
-Tests authenticate 2 users by default on setup. - This is to test multi-user functionality like agent or workspace sharing.
+Tests authenticate 4 users 1 admin, 1 editor, 1 editor2, and 1 regular by default on setup. - This is to test multi-user functionality like agent or workspace sharing. These users are defined in `tests/constants/test-users.ts`.
 
-To test as an authenticated user (nearly all tests), you can use the `test.use({ storageState: 'tests/.auth/user1.json' });` in the test file. Without this, the test will run as an unauthenticated user. This can go in the describe block or the test block.
+To test as an authenticated user (nearly all tests), you can use the `test.use({ storageState: TEST_USERS.editor.authFile });` or `test.use({ storageState: TEST_USERS.editor2.authFile });` or `test.use({ storageState: TEST_USERS.regular.authFile });` or `test.use({ storageState: TEST_USERS.admin.authFile });` in the test file. Without this, the test will run as an unauthenticated user. This can go in the describe block or the test block.
 
 ### Multi-User Testing
 
@@ -116,8 +105,9 @@ Playwright is designed to run tests in parallel. This means that each test will
 
 ```typescript
 // Most tests use single user authentication
+import { TEST_USERS } from '../constants/test-users';
 test.describe('Agent Creation', () => {
-  test.use({ storageState: 'tests/.auth/user1.json' });
+  test.use({ storageState: TEST_USERS.editor.authFile });
 
   test('should create agent', async ({ page }) => {
     // Test logic here
@@ -128,8 +118,9 @@ test.describe('Agent Creation', () => {
 #### User 2 Only
 
 ```typescript
+import { TEST_USERS } from '../constants/test-users';
 test.describe('Agent Creation', () => {
-  test.use({ storageState: 'tests/.auth/user2.json' });
+  test.use({ storageState: TEST_USERS.editor2.authFile });
 
   test('should create agent', async ({ page }) => {
     // Test logic here
@@ -142,17 +133,18 @@ test.describe('Agent Creation', () => {
 This is the most common use case for multi-user testing.
 
 ```typescript
+import { TEST_USERS } from '../constants/test-users';
 test.describe('Agent Sharing', () => {
   test('user sharing workflow', async ({ browser }) => {
     // User1 creates agent
     const user1Context = await browser.newContext({
-      storageState: 'tests/.auth/user1.json',
+      storageState: TEST_USERS.editor.authFile,
     });
     const user1Page = await user1Context.newPage();
 
     // User2 interacts with shared agent
     const user2Context = await browser.newContext({
-      storageState: 'tests/.auth/user2.json',
+      storageState: TEST_USERS.editor2.authFile,
     });
     const user2Page = await user2Context.newPage();
   });
@@ -213,30 +205,20 @@ const agentName = `Test Agent ${testSuffix}`;
 
 ### Debug Commands
 
-See [https://playwright.dev/docs/test-cli](https://playwright.dev/docs/test-cli) for more information.
-
-Some useful commands to help you debug your tests:
-
 ```bash
 # Run specific test with browser visible
 pnpm test:e2e -- tests/agents/agent-creation.spec.ts --headed
 
 # Debug mode with breakpoints
-pnpm test:e2e:debug -- --debug
+pnpm test:e2e:debug
 
 # Run single test
-pnpm test:e2e -- -g "should create agent"
+npx playwright test -g "should create agent"
 
 # Generate test report
-pnpm test:e2e -- show-report
+npx playwright show-report
 ```
 
-### VSCode/Cursor Debugging
-
-You can use the VSCode extension to debug and help write your tests, it's a great way to get started:
-
-See [https://playwright.dev/docs/getting-started-vscode](https://playwright.dev/docs/getting-started-vscode) for more information.
-
 ### Debug Helpers
 
 Add debug information to tests:
@@ -286,9 +268,9 @@ Tests run automatically on GitHub Actions with:
 
 ```typescript
 import { test, expect } from '@playwright/test';
-
+import { TEST_USERS } from '../constants/test-users';
 test.describe('Your Feature', () => {
-  test.use({ storageState: 'tests/.auth/user1.json' });
+  test.use({ storageState: TEST_USERS.editor.authFile });
 
   test('should perform action', async ({ page }) => {
     // Navigate to page
@@ -310,12 +292,13 @@ test.describe('Your Feature', () => {
 ### Multi-User Test Template
 
 ```typescript
+import { TEST_USERS } from '../constants/test-users';
 test('multi-user workflow', async ({ browser }) => {
   const testId = Date.now().toString(36);
 
   // User1 setup
   const user1Context = await browser.newContext({
-    storageState: 'tests/.auth/user1.json',
+    storageState: TEST_USERS.editor.authFile,
   });
   const user1Page = await user1Context.newPage();