feat(e2e): implement functional test suite for calendar, transactions, accounts, and CSV import

- Updated status of Feature 062 to implemented in documentation.
- Added comprehensive E2E tests for calendar navigation, transaction management, account management, and CSV import workflows.
- Introduced local execution guard to ensure tests run only in local environments.
- Created helper methods for generating test data and managing local execution.
- Added VS Code tasks for easy execution of the functional test suite locally and in demo environments.
- Documented local execution steps and CI exclusion strategy for new tests.

Author: fortinbra

.vscode/tasks.json

@@ -0,0 +1,41 @@
+{
+	"version": "2.0.0",
+	"tasks": [
+		{
+			"label": "E2E: Functional 062 (Local)",
+			"type": "shell",
+			"command": "dotnet",
+			"args": [
+				"test",
+				"c:\\ws\\BudgetExperiment\\tests\\BudgetExperiment.E2E.Tests\\BudgetExperiment.E2E.Tests.csproj",
+				"--filter",
+				"Category=Functional"
+			],
+			"options": {
+				"env": {
+					"RUN_E2E_TESTS": "true",
+					"BUDGET_APP_URL": "http://localhost:5099"
+				}
+			},
+			"group": "test"
+		},
+		{
+			"label": "E2E: Functional 062 (DemoSafe)",
+			"type": "shell",
+			"command": "dotnet",
+			"args": [
+				"test",
+				"c:\\ws\\BudgetExperiment\\tests\\BudgetExperiment.E2E.Tests\\BudgetExperiment.E2E.Tests.csproj",
+				"--filter",
+				"Category=Functional&Category=DemoSafe"
+			],
+			"options": {
+				"env": {
+					"RUN_E2E_TESTS": "true",
+					"BUDGET_APP_URL": "https://budgetdemo.becauseimclever.com"
+				}
+			},
+			"group": "test"
+		}
+	]
+}

docs/062-functional-e2e-test-suite.md

@@ -1,5 +1,5 @@
 # Feature 062: Functional E2E Test Suite
-> **Status:** 🗒️ Planning
+> **Status:** ✅ Implemented
 > **Priority:** Medium
 
 ## Overview
@@ -118,10 +118,10 @@ tests/BudgetExperiment.E2E.Tests/
 **Objective:** Validate calendar display and navigation
 
 **Tasks:**
-- [ ] Create `CalendarTests.cs`
-- [ ] Test calendar loads and displays current month
-- [ ] Test month navigation
-- [ ] Test daily transaction display
+- [x] Create `CalendarTests.cs`
+- [x] Test calendar loads and displays current month
+- [x] Test month navigation
+- [x] Test daily transaction display
 
 **Commit:**
 - test(e2e): add calendar navigation tests
@@ -131,10 +131,10 @@ tests/BudgetExperiment.E2E.Tests/
 **Objective:** Validate starting balance in running balance calculation
 
 **Tasks:**
-- [ ] Add starting balance validation tests to `CalendarTests.cs`
-- [ ] Verify running balance starts with account starting balance
-- [ ] Verify running balance accumulates correctly with transactions
-- [ ] Test account switching updates running balance
+- [x] Add starting balance validation tests to `CalendarTests.cs`
+- [x] Verify running balance starts with account starting balance
+- [x] Verify running balance accumulates correctly with transactions
+- [x] Test account switching updates running balance
 
 **Commit:**
 - test(e2e): validate starting balance in calendar
@@ -144,11 +144,11 @@ tests/BudgetExperiment.E2E.Tests/
 **Objective:** Validate transaction management
 
 **Tasks:**
-- [ ] Create `TransactionTests.cs`
-- [ ] Test create transaction flow
-- [ ] Test edit transaction flow
-- [ ] Test delete transaction flow
-- [ ] Verify calendar updates after changes
+- [x] Create `TransactionTests.cs`
+- [x] Test create transaction flow
+- [x] Test edit transaction flow
+- [x] Test delete transaction flow
+- [x] Verify calendar updates after changes
 
 **Commit:**
 - test(e2e): add transaction CRUD tests
@@ -158,10 +158,10 @@ tests/BudgetExperiment.E2E.Tests/
 **Objective:** Validate account management and CSV import
 
 **Tasks:**
-- [ ] Create `AccountTests.cs`
-- [ ] Create `CsvImportTests.cs`
-- [ ] Test account creation and switching
-- [ ] Test CSV import end-to-end
+- [x] Create `AccountTests.cs`
+- [x] Create `CsvImportTests.cs`
+- [x] Test account creation and switching
+- [x] Test CSV import end-to-end
 
 **Commit:**
 - test(e2e): add account and import tests
@@ -174,6 +174,23 @@ tests/BudgetExperiment.E2E.Tests/
 - Demo environment with seeded data
 - Feature 059 (Performance E2E) for shared fixtures
 
+## Local Execution
+
+- Run in VS Code task runner:
+    - `E2E: Functional 062 (Local)`
+    - `E2E: Functional 062 (DemoSafe)`
+- Task file: `.vscode/tasks.json`
+- Local task sets:
+    - `RUN_E2E_TESTS=true`
+    - `BUDGET_APP_URL=http://localhost:5099`
+- Local task command:
+    - `dotnet test c:\ws\BudgetExperiment\tests\BudgetExperiment.E2E.Tests\BudgetExperiment.E2E.Tests.csproj --filter "Category=Functional"`
+- DemoSafe task sets:
+    - `RUN_E2E_TESTS=true`
+    - `BUDGET_APP_URL=https://budgetdemo.becauseimclever.com`
+- DemoSafe task command:
+    - `dotnet test c:\ws\BudgetExperiment\tests\BudgetExperiment.E2E.Tests\BudgetExperiment.E2E.Tests.csproj --filter "Category=Functional&Category=DemoSafe"`
+
 ---
 
 ## Related Features
@@ -188,3 +205,6 @@ tests/BudgetExperiment.E2E.Tests/
 | Date | Author | Description |
 |------|--------|-------------|
 | 2026-02-01 | AI | Created feature doc, consolidated Feature 041 scenarios |
+| 2026-02-14 | AI | Implemented functional Playwright suite: Calendar, Transaction, Account, CSV Import tests + local-run guidance |
+| 2026-02-14 | AI | Added VS Code local task for one-click Feature 062 functional suite execution |
+| 2026-02-14 | AI | Added VS Code DemoSafe task for shared-environment functional validation |

docs/068-playwright-local-critical-flows.md

@@ -0,0 +1,177 @@
+# Feature 068: Playwright Local Critical User Flows
+> **Status:** 🗒️ Planning  
+> **Priority:** High  
+> **Estimated Effort:** Small (< 1 sprint)  
+> **Dependencies:** Feature 062 (Functional E2E Test Suite)
+
+## Overview
+
+Define and implement a focused Playwright E2E coverage baseline for the most critical day-to-day user journeys in the local development environment. This feature intentionally limits scope to three flows: adding transactions, adding accounts, and adding categories.
+
+Tests are designed to run against the local API-hosted client during development and debugging, while remaining excluded from GitHub Actions until the suite is stabilized.
+
+## Problem Statement
+
+### Current State
+
+- E2E direction exists, but core create flows are not guaranteed by a single minimal, high-signal local suite.
+- Developers can introduce regressions in critical create workflows without immediate local Playwright feedback.
+- CI execution scope for E2E is intentionally conservative and should not be expanded yet.
+
+### Target State
+
+- A small Playwright suite validates the three core creation workflows end-to-end.
+- Tests are easy to run locally against the standard development host.
+- GitHub Actions does not execute this new local-critical suite yet.
+
+---
+
+## User Stories
+
+### Core Local E2E Coverage
+
+#### US-068-001: Add Transaction Flow
+**As a** developer  
+**I want to** validate the transaction creation flow end-to-end with Playwright locally  
+**So that** transaction input regressions are caught early
+
+**Acceptance Criteria:**
+- [ ] Playwright test creates a transaction through the UI on local environment
+- [ ] Saved transaction appears in the expected list/calendar context
+- [ ] Test asserts success feedback and persisted visible result
+
+#### US-068-002: Add Account Flow
+**As a** developer  
+**I want to** validate account creation end-to-end with Playwright locally  
+**So that** account setup regressions are caught before merge
+
+**Acceptance Criteria:**
+- [ ] Playwright test creates an account through the UI on local environment
+- [ ] New account is selectable/visible in account UI
+- [ ] Test asserts resulting state reflects the created account
+
+#### US-068-003: Add Category Flow
+**As a** developer  
+**I want to** validate category creation end-to-end with Playwright locally  
+**So that** category-management regressions are detected quickly
+
+**Acceptance Criteria:**
+- [ ] Playwright test creates a category through the UI on local environment
+- [ ] New category appears in category management UI and is usable in relevant forms
+- [ ] Test asserts created category can be selected where applicable
+
+#### US-068-004: Local-Only Execution Scope
+**As a** maintainer  
+**I want to** keep this suite local-only for now  
+**So that** CI runtime and flakiness risk stay controlled while scenarios mature
+
+**Acceptance Criteria:**
+- [ ] Local command/documentation exists for running the critical Playwright suite
+- [ ] GitHub Actions workflows do not run this new suite
+- [ ] CI exclusion approach is explicit and documented (e.g., path/suite filter or separate non-invoked workflow)
+
+---
+
+## Technical Design
+
+### Test Architecture
+
+Target structure in `tests/BudgetExperiment.E2E.Tests`:
+
+- `Tests/FunctionalTests/TransactionCreateTests.cs`
+- `Tests/FunctionalTests/AccountCreateTests.cs`
+- `Tests/FunctionalTests/CategoryCreateTests.cs`
+
+Common conventions:
+- Use resilient selectors (role/label/test-id based where available)
+- Use unique test data suffixes to avoid collisions
+- Keep each test independent and cleanup-safe when practical
+
+### Local Environment Execution
+
+Per repository workflow, run only the API project locally (the API hosts the Blazor client):
+
+```powershell
+dotnet run --project c:\ws\BudgetExperiment\src\BudgetExperiment.Api\BudgetExperiment.Api.csproj
+```
+
+Then execute the focused Playwright E2E tests for these critical flows.
+
+### CI Exclusion Strategy (Initial)
+
+For this feature phase, keep execution local-only by one of the following:
+- Ensure existing GitHub Action test filters do not include these specific tests, or
+- Place them under a naming/category convention that current CI selection excludes.
+
+No change is required to enable CI execution in this feature. A future feature can promote these tests into CI once stability is proven.
+
+---
+
+## Implementation Plan
+
+### Phase 1: Add Focused Local Critical Flow Tests
+
+**Objective:** Introduce the three high-value create-flow Playwright tests.
+
+**Tasks:**
+- [ ] Add transaction create E2E test
+- [ ] Add account create E2E test
+- [ ] Add category create E2E test
+- [ ] Verify all three pass locally against API-hosted client
+
+**Commit:**
+- `test(e2e): add local critical create-flow playwright tests`
+
+### Phase 2: Ensure CI Exclusion and Document Local Run Path
+
+**Objective:** Keep suite local-only and make intent explicit.
+
+**Tasks:**
+- [ ] Verify GitHub Actions does not execute this critical local suite
+- [ ] Document local run commands and prerequisites
+- [ ] Document CI exclusion rationale in test docs/workflow notes
+
+**Commit:**
+- `docs(ci): document local-only execution for critical playwright flows`
+
+---
+
+## Testing Strategy
+
+### E2E Scenarios (Playwright)
+
+- [ ] Create transaction and verify visibility in primary transaction/calendar UI
+- [ ] Create account and verify it appears/selects in account controls
+- [ ] Create category and verify it appears in category UI and transaction category picker
+
+### Manual Verification Checklist
+
+- [ ] Start API locally and confirm client is served
+- [ ] Run focused Playwright critical-flow tests locally
+- [ ] Confirm tests are not included in current GitHub Actions execution
+
+---
+
+## Risks and Mitigations
+
+- **Risk:** UI selector instability causes flaky tests.  
+  **Mitigation:** Prefer semantic selectors and add stable test IDs only where needed.
+- **Risk:** Local data collisions across repeated runs.  
+  **Mitigation:** Use unique test data identifiers and isolate scenarios.
+- **Risk:** Future drift between local and CI expectations.  
+  **Mitigation:** Keep CI exclusion explicitly documented and revisit in a follow-up feature.
+
+---
+
+## Related Features
+
+- Feature 062: Functional E2E Test Suite
+- Feature 059: Performance E2E tests
+
+---
+
+## Changelog
+
+| Date | Author | Description |
+|------|--------|-------------|
+| 2026-02-14 | AI | Created feature doc for local-only Playwright critical create-flow coverage |

tests/BudgetExperiment.E2E.Tests/Helpers/LocalExecutionGuard.cs

@@ -0,0 +1,27 @@
+// <copyright file="LocalExecutionGuard.cs" company="BecauseImClever">
+// Copyright (c) BecauseImClever. All rights reserved.
+// </copyright>
+
+namespace BudgetExperiment.E2E.Tests.Helpers;
+
+/// <summary>
+/// Guard utilities for environment-sensitive E2E tests.
+/// </summary>
+public static class LocalExecutionGuard
+{
+    /// <summary>
+    /// Skips the current test when the target base URL is not local.
+    /// </summary>
+    /// <param name="baseUrl">Current test base URL.</param>
+    public static bool IsLocalBaseUrl(string baseUrl)
+    {
+        if (!Uri.TryCreate(baseUrl, UriKind.Absolute, out var uri))
+        {
+            return false;
+        }
+
+        return uri.Host.Equals("localhost", StringComparison.OrdinalIgnoreCase)
+            || uri.Host.Equals("127.0.0.1", StringComparison.OrdinalIgnoreCase)
+            || uri.Host.Equals("::1", StringComparison.OrdinalIgnoreCase);
+    }
+}

tests/BudgetExperiment.E2E.Tests/Helpers/TestDataHelper.cs

@@ -0,0 +1,42 @@
+// <copyright file="TestDataHelper.cs" company="BecauseImClever">
+// Copyright (c) BecauseImClever. All rights reserved.
+// </copyright>
+
+namespace BudgetExperiment.E2E.Tests.Helpers;
+
+/// <summary>
+/// Helper methods for generating deterministic E2E test data.
+/// </summary>
+public static class TestDataHelper
+{
+    /// <summary>
+    /// Creates a unique, readable name for test-created entities.
+    /// </summary>
+    /// <param name="prefix">Name prefix (for example: Account, Txn).</param>
+    /// <returns>A unique name safe for UI assertions.</returns>
+    public static string CreateUniqueName(string prefix)
+    {
+        return $"E2E-{prefix}-{DateTime.UtcNow:yyyyMMddHHmmss}-{Guid.NewGuid():N}"[..48];
+    }
+
+    /// <summary>
+    /// Finds a sample CSV file from the repository's sample data folder.
+    /// </summary>
+    /// <returns>Absolute path to sample data CSV.</returns>
+    public static string GetSampleCsvPath()
+    {
+        var current = new DirectoryInfo(AppContext.BaseDirectory);
+        while (current != null)
+        {
+            var candidate = Path.Combine(current.FullName, "sample data", "boa.csv");
+            if (File.Exists(candidate))
+            {
+                return candidate;
+            }
+
+            current = current.Parent;
+        }
+
+        throw new FileNotFoundException("Could not locate sample CSV file at sample data/boa.csv from test execution directory.");
+    }
+}