Testing Strategy

Relevant source files

The following files were used as context for generating this wiki page:

• tests/qr-helpers.test.js
• src/App.test.js
• package.json
• src/utils/qr-helpers.js
• src/App.jsx
• README.md
• SECURITY_AUDIT_REPORT.md

The testing strategy for QR-Tool focuses on ensuring the correctness and reliability of core business logic and utility functions through unit tests. The project utilizes the Vitest testing framework, which is integrated into the Vite development environment. The strategy covers data generation, validation helpers, and color manipulation logic.

In addition to unit tests, the project incorporates security auditing of its dependencies as a key part of its quality assurance process. Tests are organized within the tests/ directory and are executed via npm scripts, providing a streamlined workflow for developers to validate changes.

Test Framework and Environment

The project uses Vitest as its primary testing framework, configured to run in a jsdom environment. This allows for testing code that may interact with browser-like structures without needing a full browser. The configuration and dependencies are defined in package.json.

• Framework: Vitest
• Test Runner: vitest
• Environment: jsdom
• Dependencies: vitest, jsdom

Sources: package.json:19,28-29

Test Execution

Testing is managed through npm scripts defined in package.json.

Script	Description
npm test	Runs all tests once.
npm run test:watch	Runs tests in watch mode, re-running them on file changes.

This diagram shows the commands used to run tests.

Unit Testing

The core of the testing strategy is unit testing. Tests are structured using describe blocks to group related tests and it blocks for individual test cases. Assertions are made using Vitest's expect API.

Helper Function Tests

A comprehensive suite of tests exists for the utility functions defined in src/utils/qr-helpers.js. These tests, located in tests/qr-helpers.test.js, validate the correctness of various helper categories.

This diagram illustrates the relationship between the helper functions and their corresponding test file.

The following table summarizes the functions under test:

Category	Function	Description
Color Helpers	relLum	Calculates relative luminance of a hex color.
	getContrastRatio	Calculates the WCAG contrast ratio between two luminances.
	normalizeHex	Converts 3-digit hex colors to 6-digit format.
	isValidHex	Validates if a string is a valid hex color.
Validation Helpers	isValidURL	Validates URL format (empty is considered valid).
	isSafeHttpUrl	Ensures a URL uses only http: or https: protocols.
	isValidEmail	Validates email address format.
	isValidPhone	Validates phone number format.
	isValidLatLng	Validates latitude and longitude coordinates.
ECC Helpers	pickECC	Automatically selects an Error Correction Code (ECC) level based on logo size and color contrast.
	estimateDimension	Estimates the required QR code dimension based on data length and ECC level.
Canvas Export	exportWithPadding	Tests are skipped (it.skip) as they require a full canvas environment.
	roundRectPath	Tests are skipped.
	buildDataURL	Tests are skipped.

Sources: tests/qr-helpers.test.js:8-105

Business Logic Tests

The primary business logic for generating QR code content strings is tested in src/App.test.js. The generateQRContent function, which is copied from src/App.jsx for isolated testing, is thoroughly validated across all supported QR code types.

The tests cover:

• Correct string generation for each QR type (URL, Text, Wi-Fi, vCard, etc.).
• Proper escaping of special characters for Wi-Fi and vCard data.
• Correct handling of optional fields and empty inputs.
• Encoding of non-ASCII characters (e.g., Vietnamese).
• Edge cases, such as unknown types or null data.

This flowchart shows the testing logic for the generateQRContent function.

It is important to note that src/App.test.js does not perform component-level testing (e.g., rendering the App component and simulating user interactions). Instead, it extracts and tests the generateQRContent pure function in isolation.

Sources: src/App.test.js:6-101

QR Code Scanning Test

The application includes a mechanism to verify that a generated QR code is scannable. This is handled by the testQRScan utility.

The process is as follows:

1. After a QR code is rendered to a <canvas>, the testQRScan function is invoked.
2. This function attempts to decode the QR code from the canvas image.
3. The result (success, warning, or error) is set in the application's state and displayed to the user.
4. For very large QR codes (size > 2048px), the detailed scan is skipped to avoid performance issues, and a success message is shown by default.

Security Testing

The project's quality assurance includes security testing, primarily through dependency vulnerability scanning. The npm audit command is used to check for known vulnerabilities in the project's dependencies.

The SECURITY_AUDIT_REPORT.md file documents the process and results of these audits, including vulnerabilities found and the steps taken to remediate them. This proactive approach ensures that third-party packages do not introduce security risks.

• Command: npm audit
• Goal: Identify and fix vulnerabilities in dependencies.
• Documentation: Results are recorded in SECURITY_AUDIT_REPORT.md.

Sources: SECURITY_AUDIT_REPORT.md:21-34, README.md:143-145

Summary

The testing strategy for QR-Tool is robust and multi-faceted, providing good coverage for critical application logic. It combines automated unit tests using Vitest for helper functions and data generation, an in-app QR code scanning validation, and security auditing of dependencies. While it heavily emphasizes unit testing of pure functions, it currently lacks component-level interaction tests. The strategy is well-documented and integrated into the development workflow through clear npm scripts.