Docs / Testing & QA

Testing and QA Documentation

This page documents the testing strategy, automated suites, execution flow, coverage model, QA expectations, and release verification process for Vendventory. It explains how the application is validated across authentication, settings, dashboard, products, purchases, stock-outs, stock adjustments, reports, permissions, and async utility endpoints.

Core testing objective: protect the app against behavioral regressions, permission leaks, module route failures, inventory posting mistakes, and configuration-driven runtime issues before changes reach production.

Primary outcomes

Routes should load or fail intentionally.
Protected endpoints must reject unauthorized users.
Inventory workflows must preserve stock and ledger correctness.
Settings and AI runtime values must be saved and applied predictably.
Module screens must stay operational after refactors.

Current automated focus

Feature tests using Pest with database refresh isolation.
HTTP route and permission smoke coverage across admin and self-service modules.
Workflow verification for stock-outs, user/profile security actions, and admin tools.
CRUD modernization coverage for categories, units, suppliers, purchases, and settings save flows.
Reviewer storyboard seeding checks for branch-aware POS demo data.
JSON endpoint payload checks for async pages and operational actions.
Practical regression protection instead of low-value micro-unit tests.

Testing Overview

The testing approach used in Vendventory is intentionally practical. It does not try to unit test every trivial getter or every Blade conditional. Instead, it focuses on the areas most likely to cause real operational damage: route access, permissions, stock movement, configuration persistence, AI runtime state, and reporting entry points.

This means the suite combines HTTP-level feature coverage with workflow-specific service verification. That combination provides good confidence without making the suite unreasonably slow or fragile.

Why this strategy works

HTTP tests verify middleware, route names, controller integration, and rendered views in a single pass.
Workflow tests validate stock math, reference generation, deletion rules, and database side effects where a simple page load is not enough.
JSON endpoint tests guard the async pieces that modern screens depend on.
Runtime configuration tests protect sensitive settings behavior such as encrypted AI API keys and dynamic config loading.

Current Automated Suite Inventory

The project currently contains several focused feature suites. Together they form the baseline automated QA layer for the application.

Key test files

tests/Feature/AdminModuleCoverageTest.php: broad route smoke coverage for module index, create, edit, self-service pages, and async endpoints.
tests/Feature/StockOutModuleTest.php: stock-out deletion rules, bulk delete behavior, reference generation, store flow, and update flow.
tests/Feature/UserProfileModuleTest.php: admin user creation, avatar/profile updates, password-request approval and rejection, session revocation, and password-reset completion tracking.
tests/Feature/SettingsToolsDiagnosticsTest.php: diagnostics payload structure, permission gating, refresh-database confirmation, and acting-user preservation.
tests/Feature/AiSettingsTest.php: AI settings persistence, encryption, runtime status, and connection test behavior.
tests/Feature/ReportExportsTest.php: dashboard and reporting export responses for protected report surfaces.

Important: the suite is intentionally split by behavior instead of by folder alone. That makes it easier to keep each test file focused on one operational concern.

Module Coverage Summary

The expanded smoke suite verifies that the app can still load the major administrative entry points after application changes. This is especially useful when routes, services, permissions, providers, views, or module sidebars are refactored.

Modules covered by the smoke suite

Dashboard
Settings
Roles
Permissions
Categories
Units
Suppliers
Notifications
Products
Purchases
Stock Outs
Stock Adjustments
Inventory Valuation report
Purchase Cost report
Supplier Spend report
Expiry Risk report
Loss Reasons report
Stock Movement report
Adjustment Variance report

Route types covered by the smoke suite

Index pages: the main landing screen for each module.
Create pages: new-record forms and their supporting data loading.
Edit pages: draft or editable records with bound route models.
Async endpoints: history drawers, reference number generators, and tool execution endpoints.
Permission checks: guest redirects, authenticated 403 behavior, and authorized success paths.

What the Admin Module Smoke Suite Verifies

The route smoke suite is not just a collection of random page loads. It follows a deliberate pattern so that each route class is verified in the same way.

Smoke suite verification model

Guest request: protected pages should redirect to the login page.
Authenticated without permission: permission-protected routes should respond with 403 Forbidden.
Authenticated with permission: the route should return 200 OK and render the expected view or JSON payload.
Bound model routes: edit and detail pages should remain resolvable with valid records.
Async utility routes: endpoints used by JavaScript screens should continue to return the expected response structure.

This suite is especially valuable after route renaming, middleware changes, provider refactors, permission string changes, view moves, or controller and service constructor changes.

Specialized Workflow Suites

Some parts of the application deserve deeper validation than a simple route smoke test. Those areas have dedicated suites that validate business logic and database side effects.

Stock Out workflow coverage

Draft delete behavior
Locked completed record protection
Bulk delete skip logic
Reference number generation
Completed stock posting and balance updates
Draft-to-completed update flow

AI and copilot coverage

Encrypted API key storage
Dynamic runtime config application
Runtime health and status responses
Connection test metadata recording
Copilot permission enforcement
Fallback analytics-only answer mode

Test Environment and Database Strategy

The automated feature suite runs against a dedicated testing environment. The test runtime is intentionally isolated from normal local development data.

Key environment characteristics

APP_ENV=testing: application services run in test mode.
DB_CONNECTION=sqlite: tests use SQLite during automated execution.
DB_DATABASE=:memory:: the database lives in memory for fast and clean test runs.
SESSION_DRIVER=array: no persistent session storage is required.
CACHE_STORE=array: runtime cache resets cleanly for test execution.
QUEUE_CONNECTION=sync: queued jobs execute immediately inside the test process where applicable.

Refresh strategy: most feature tests use RefreshDatabase, which ensures database state is rebuilt cleanly between test cases. This avoids hidden dependencies between tests.

Middleware and Permission Testing

Route protection is one of the most important risk areas in an admin inventory system. A page that loads for the wrong user is not a cosmetic bug; it is a security and operational bug.

How permission tests are structured

The installation middleware is disabled in test setup when it is unrelated to the scenario.
Permission cache is cleared before each test.
Required permissions are seeded explicitly using Spatie permission records.
Users are created with either no permission or the exact permission set needed for the route.
Responses are validated for redirect, forbidden, or success behavior depending on the scenario.

beforeEach(function () {
    $this->withoutMiddleware(EnsureAppIsInstalled::class);
    app(PermissionRegistrar::class)->forgetCachedPermissions();
});

$user = adminModuleUser(['view products'], ['view products']);

$response = $this->actingAs($user)->get(route('products.index'));
$response->assertOk();

Running the Test Suite

The fastest way to run the full automated suite is through Laravel's standard test command. Developers can also target a single file, a single class, or a filtered subset while working on a specific feature.

Common commands

php artisan test
php artisan test tests/Feature/AdminModuleCoverageTest.php
php artisan test tests/Feature/StockOutModuleTest.php
php artisan test --filter=AiSettingsTest
php artisan test --filter=CopilotEndpointsTest

Suggested usage pattern

Run the single changed test file first.
Run the most closely related workflow suite second.
Run the full feature suite before merging.
If configuration or providers changed, rerun the broad smoke suite even if the main feature is unrelated.

Coverage by Application Area

Dashboard and reports

Entry pages are smoke tested so they continue to render.
Report detail entry points such as Inventory Valuation detail are verified with bound product models.
The goal here is route and view continuity, because reporting screens combine many aggregates and are sensitive to refactors.

Inventory workflows

Stock-outs receive deeper business logic tests because they directly affect balances, movements, reference generation, and deletion policy.
Stock adjustments currently receive broad module route coverage and manual smoke guidance, with dedicated posting tests still a strong future candidate.
Purchase create, edit, and reference-generation flows are smoke covered at the module level.

AI, settings, and admin tools

Sensitive secrets such as API keys are verified for encrypted storage.
Runtime config application is verified so saved settings actually become active config values.
Diagnostics endpoints are checked for payload structure and permission enforcement, and the Refresh Database action is tested for exact confirmation-phrase handling.
Copilot routes are checked for guest blocking, permission enforcement, runtime mode, and fallback behavior when AI credentials are unavailable.

Fixture and Helper Patterns

The test suite uses helper functions to build realistic, minimal records quickly. This keeps tests readable while still exercising actual Eloquent relationships and route model binding.

Fixture helpers used in the smoke suite

adminModuleCategory()
adminModuleUnit()
adminModuleSupplier()
adminModuleProduct()
adminModulePurchase()
adminModuleStockOut()
adminModuleStockAdjustment()
adminModuleUser()

$product = adminModuleProduct($user, [
    'current_stock' => 20,
    'cost_price' => 12,
    'selling_price' => 18,
]);

$stockOut = adminModuleStockOut($user, $product, [
    'status' => 'draft',
]);

These helpers intentionally create valid minimum records. They are not meant to replace richer scenario builders where exact financial or inventory behavior must be asserted.

How to Add New Tests Correctly

When extending the suite, new tests should be added with the same discipline used by the existing files. The objective is not to inflate test count. The objective is to add meaningful regression protection.

Recommended authoring rules

Test behavior, not implementation trivia.
Prefer full route tests for access control and view continuity.
Prefer focused service tests for stock posting, totals, and deletion logic.
Seed the minimum required permissions explicitly.
Use realistic status values such as draft, completed, and cancelled.
Assert both response payloads and database side effects when the workflow changes data.

Good candidates for additional tests

Stock adjustment posting and rollback behavior
Installer step flow end-to-end coverage
Purchase invoice view and PDF access rules
Notification bulk actions and open behavior
Report filters with non-empty seeded datasets
Product delete flows affecting related purchases

Response Expectations and Status Rules

Expected outcomes by scenario

Guest: usually redirect to login for standard web pages.
Authenticated without permission: 403 Forbidden.
Authorized page route: 200 OK with the intended Blade view.
Authorized JSON route: structured success payload with expected keys.
Locked inventory record: operation rejected with explicit error message.

Manual QA Checklist Before Release

Automated tests reduce risk, but they do not replace a quick manual release check for complex UI and integration-heavy flows.

Recommended release checklist

Run the full automated feature suite.
Open dashboard, products, purchases, stock-outs, stock adjustments, and reports manually.
Verify at least one create flow and one edit flow in inventory-related modules.
Confirm permission-restricted pages still block a lower-privileged user.
Verify AI settings save correctly if AI-related code changed.
Check documentation links if navigation was changed.

Troubleshooting Failing Tests

When a test fails, the failure type usually points directly at the area that broke. The key is to diagnose the category of failure first instead of editing the test blindly.

Common failure categories

302 instead of 200: auth or middleware changed unexpectedly.
403 instead of 200: permission string changed or permission not granted.
500 error: controller, view, provider, or helper regression.
Missing JSON key: endpoint payload shape changed.
Database assertion mismatch: workflow side effect changed or data fixture is no longer realistic.

Recommended debugging order

Read the failing route or workflow name carefully.
Check middleware and permission strings first.
Check route names and bound model parameters.
Check controller return type and view name.
Check service side effects if a database assertion failed.
Only then adjust fixtures if the app logic is still correct.

Recommended CI and Merge Gate Flow

Automated tests are most useful when they run consistently before merge and before deployment. A practical CI flow for this project should remain simple and predictable.

Recommended pipeline order

Install composer dependencies.
Prepare the test environment.
Run automated feature tests.
Fail the build if any route smoke test breaks.
Publish release only after manual QA signoff.

composer install
php artisan test

# optional targeted rerun when investigating
php artisan test --filter=AdminModuleCoverageTest

Coverage Gaps and Future Improvements

The current suite is a strong baseline, but it is not the final shape of quality assurance. Some areas can be expanded further when time and release pressure allow.

Recommended next improvements

Add deeper stock adjustment posting tests, matching the strength of stock-out workflow tests.
Add seeded report dataset tests so charts and summary metrics are checked with non-empty data.
Add purchase invoice and email flow tests.
Add notification interaction tests for read, unread, bulk delete, and redirect behavior.
Add browser-level smoke checks if the UI grows more dynamic.

Important Notes

Things to remember

Do not remove a failing test just to make the suite green.
If a route name changes, update both the app and the test intentionally.
Permission string case and spelling matter.
Inventory workflows should always be validated with side-effect assertions, not only status codes.
Documentation should evolve with the suite so new contributors understand the current QA model.
Broad smoke coverage is not a replacement for deep business-rule tests. Both layers are necessary.