Test Documentation
Comprehensive testing documentation for the Free For Charity Admin Portal
About Testing
This project includes 17 comprehensive test suites with 179 automated tests that validate every aspect of the application from configuration to deployment.
Testing is integrated into the CI/CD pipeline and runs automatically on every pull request. All tests must pass before code can be merged to the main branch.
Test Suites
17
Organized by category
Total Tests
179
All passing
CI/CD
Automated
Every PR & deployment
Configuration & Build
Tests that validate project configuration files and build tooling setup. These ensure consistent development environments and catch configuration errors early.
Configuration Validation
__tests__/config-validation.test.js
Purpose
Validates that all project configuration files are correctly set up and consistent
What It Tests
- package.json structure and required fields
- Node.js version requirement matches CI environment
- Package manager lock file (pnpm-lock.yaml) existence and validity
- Script commands availability (build, test, lint, format)
- DevDependencies are properly declared
Why It's Important
Configuration errors can cause silent failures in CI/CD pipelines. These tests catch misconfigurations before deployment, ensuring consistent behavior across development and production environments.
Manual Verification
Run `pnpm install --frozen-lockfile` to verify lock file integrity. Check that `pnpm run build`, `pnpm test`, and `pnpm run lint` all execute without errors.
Related Documentation
EditorConfig
__tests__/editorconfig.test.js
Purpose
Ensures EditorConfig file exists and is properly formatted for IDE consistency
What It Tests
- .editorconfig file existence
- Basic structure validation
- Common settings presence (indent_style, indent_size, end_of_line)
- File is readable and parseable
Why It's Important
EditorConfig ensures consistent coding style across different editors and IDEs. This prevents formatting inconsistencies that can cause merge conflicts and code review noise.
Manual Verification
Open .editorconfig and verify it contains settings for indent_style, indent_size, end_of_line, and charset. Confirm your IDE respects these settings when editing files.
Related Documentation
Commitlint Configuration
__tests__/commitlint-config.test.js
Purpose
Validates commit message linting configuration for consistent commit history
What It Tests
- commitlint.config.js file existence
- Configuration extends conventional commits
- File is valid JavaScript
- Exports a configuration object
Why It's Important
Consistent commit messages improve project maintainability, enable automated changelog generation, and make git history easier to navigate and understand.
Manual Verification
Run `echo "test: example commit" | npx commitlint` to test the configuration. Valid conventional commit types include: feat, fix, docs, style, refactor, test, chore.
Related Documentation
Bundle Analyzer Configuration
__tests__/bundle-analyzer.test.js
Purpose
Validates bundle size analysis configuration for performance monitoring
What It Tests
- @next/bundle-analyzer dependency installation
- Analyze script presence in package.json
- Next.js configuration imports bundle analyzer
- ANALYZE environment variable usage
- Static export configuration preservation
Why It's Important
Bundle size directly impacts page load performance. These tests ensure the bundle analyzer is properly configured so developers can identify and address bloat before it reaches production.
Manual Verification
Run `pnpm run analyze` to generate bundle analysis reports. Review the generated HTML reports in your browser to identify large dependencies and optimization opportunities.
Related Documentation
Lighthouse Configuration
__tests__/lighthouse-config.test.js
Purpose
Validates Lighthouse CI configuration for automated performance auditing
What It Tests
- lighthouserc.json file existence and validity
- Configuration structure (ci.collect, ci.assert)
- Static distribution directory set to ./out
- Multiple URL configurations for comprehensive testing
- numberOfRuns configuration for consistent results
- Performance, accessibility, best-practices, and SEO thresholds
Why It's Important
Lighthouse audits catch performance, accessibility, and SEO issues before they impact users. Automated testing ensures quality standards are maintained with every deployment.
Manual Verification
Check the GitHub Actions "Lighthouse CI" workflow runs after deployments. Download the lighthouse-results artifact to review detailed HTML reports for each page.
Related Documentation
Workflow Dependencies
__tests__/workflow-dependencies.test.js
Purpose
Ensures GitHub Actions workflows run in the correct order to prevent premature deployment
What It Tests
- Deploy workflow runs after CI workflow completes
- Lighthouse workflow runs after successful deployment
- Workflow YAML files are valid and parseable
- workflow_run triggers are properly configured
Why It's Important
Deploying before tests complete can push broken code to production. These tests verify that deployment only happens after all quality checks pass.
Manual Verification
Push a commit to a PR and observe the Actions tab. Verify CI runs first, then deployment (on merge to main), then Lighthouse audits. No workflow should start before its dependencies complete.
Related Documentation
Build & Deployment
Tests that verify the build output is correct and ready for deployment to GitHub Pages. These prevent broken deployments and missing pages.
Build Output
__tests__/build-output.test.js
Purpose
Verifies that the build process produces the correct output structure
What It Tests
- out/ directory creation after build
- index.html (home page) existence
- tech-stack/index.html presence
- _next/ directory with JavaScript and CSS bundles
- 404.html (error page) generation
- _next/static/ directory with static assets
Why It's Important
Missing or incorrectly structured build output causes deployment failures or broken pages. These tests catch build configuration issues early.
Manual Verification
Run `pnpm run build` and inspect the out/ directory. Confirm all expected HTML files exist, _next/static/ contains CSS and JS files, and you can open out/index.html in a browser.
Related Documentation
GitHub Pages Configuration
__tests__/github-pages-config.test.js
Purpose
Ensures the site is properly configured for GitHub Pages static hosting
What It Tests
- .nojekyll file presence in output directory
- Next.js configuration has output: "export"
- Images are unoptimized for static export
- Trailing slashes enabled for proper routing
Why It's Important
Without .nojekyll, GitHub Pages Jekyll processing breaks Next.js assets. These tests prevent deployment issues that would make CSS and JavaScript fail to load.
Manual Verification
After building, verify `out/.nojekyll` exists. Check next.config.js contains output: "export", images: { unoptimized: true }, and trailingSlash: true.
Related Documentation
Route Generation
__tests__/route-generation.test.js
Purpose
Validates that all application routes are generated as static HTML pages
What It Tests
- Home page (index.html) generation
- Tech Stack page generation
- Documentation page generation
- Privacy Policy page generation
- Cookie Policy page generation
- Training Plan page generation
- All route directories contain index.html
Why It's Important
Missing route generation means 404 errors in production. These tests ensure every defined route is properly exported as a static page.
Manual Verification
After building, navigate through out/ directory and confirm each route has its own directory with an index.html file. Open each HTML file in a browser to verify it renders correctly.
Related Documentation
SEO Metadata
__tests__/seo-metadata.test.js
Purpose
Verifies that SEO-critical files are generated and properly formatted
What It Tests
- robots.txt file existence in output
- robots.txt is a valid file (not directory)
- robots.txt contains User-agent directive
- sitemap.xml file existence
- sitemap.xml is properly formatted XML
Why It's Important
robots.txt and sitemap.xml are essential for search engine crawling and indexing. Missing or malformed files can significantly harm SEO.
Manual Verification
After building, check out/robots.txt contains valid directives like "User-agent: *". Verify out/sitemap.xml is valid XML with <url> entries for each page. Test at https://www.xml-sitemaps.com/validate-xml-sitemap.html
Related Documentation
Design & Responsiveness
Tests that ensure the site works correctly on all device sizes and meets accessibility standards. These verify mobile, tablet, and desktop layouts.
Responsive Design
__tests__/responsive-design.test.js
Purpose
Validates Tailwind CSS breakpoints and responsive utility classes
What It Tests
- Tailwind CSS configuration file existence
- Responsive breakpoints (sm: 640px, md: 768px, lg: 1024px)
- Mobile-first responsive classes availability
- Utility classes for hiding/showing elements at breakpoints
- Grid and flex responsive utilities
Why It's Important
Responsive design ensures the site works on all device sizes. These tests verify that Tailwind is configured correctly for mobile, tablet, and desktop layouts.
Manual Verification
Open the site in your browser and use DevTools responsive mode (F12 → Toggle device toolbar). Test at 375px (mobile), 768px (tablet), and 1280px (desktop). Verify navigation, layout, and content adapt appropriately.
Related Documentation
Mobile Responsiveness
__tests__/mobile-responsiveness.test.js
Purpose
Validates mobile-specific behavior including navigation and viewport configuration
What It Tests
- Hamburger menu button has proper responsive classes
- Desktop navigation hidden on mobile (md:flex class)
- Mobile menu visible only on small screens
- Viewport meta tag presence and configuration
- Logo responsive behavior
Why It's Important
Mobile users represent a significant portion of traffic. These tests ensure mobile navigation works correctly and the viewport is configured for proper rendering on small screens.
Manual Verification
On a mobile device or DevTools mobile emulator at 375px width: 1) Hamburger menu should be visible, 2) Desktop links should be hidden, 3) Clicking hamburger opens the menu, 4) Page should not require horizontal scrolling.
Related Documentation
Accessibility
__tests__/accessibility.test.js
Purpose
Validates that all pages meet WCAG accessibility standards
What It Tests
- Home page accessibility violations (using axe-core)
- Tech Stack page accessibility
- Documentation page accessibility
- Cookie Policy page accessibility
- Privacy Policy page accessibility
- Training Plan page accessibility
Why It's Important
Accessibility is both a legal requirement and ethical obligation. These tests catch common issues like missing alt text, poor color contrast, and improper heading structure that would prevent users with disabilities from accessing the site.
Manual Verification
Use browser accessibility tools: 1) Chrome DevTools Lighthouse (Accessibility category), 2) WAVE browser extension, 3) Keyboard navigation test (tab through page without mouse), 4) Screen reader test (NVDA on Windows or VoiceOver on Mac).
Related Documentation
Navigation Coverage
__tests__/navigation-coverage.test.js
Purpose
Ensures all application pages are accessible through at least one navigation area
What It Tests
- All pages (Home, Tech Stack, Documentation, Testing, Training Plan, Privacy, Cookie) accessible via navigation or footer
- No orphaned pages exist that users cannot discover
- Navigation component structure (desktop and mobile menus)
- Footer component structure (Quick Links, Admin Docs, Policy links)
- External links present (GitHub, social media)
Why It's Important
Pages that exist but are not linked from any navigation area are effectively invisible to users. This test ensures complete site discoverability and prevents orphaned content.
Manual Verification
For each page in the app, verify it can be reached by: 1) Clicking a link in the top navigation (desktop or mobile), 2) Clicking a link in the footer, or 3) Direct URL entry. No page should be completely unreachable through normal navigation.
Related Documentation
Component Tests
Tests that validate individual React components render correctly and behave as expected. These catch UI bugs before they reach users.
Navigation Component
__tests__/components/Navigation.test.tsx
Purpose
Tests the Navigation component rendering, behavior, and user interactions
What It Tests
- Component renders without crashing
- Logo is displayed correctly
- Desktop navigation links render (Home, Tech Stack, Training Plan, GitHub)
- Mobile navigation includes Testing link (not in desktop)
- Hamburger menu button functionality
- Mobile menu opens and closes correctly
- Links are accessible and clickable
- ARIA attributes for accessibility
Why It's Important
The navigation is the primary way users move through the site. Broken navigation severely impacts usability and user experience.
Manual Verification
Desktop (>768px): Verify logo and inline links (Home, Tech Stack, Training Plan, GitHub) are visible. Mobile (<768px): Verify hamburger menu works - click to open, displays all navigation links including Testing, click link to close, click X to close.
Related Documentation
Footer Component
__tests__/components/Footer.test.tsx
Purpose
Tests the Footer component rendering and link functionality
What It Tests
- Component renders correctly
- Copyright text displays with current year
- Privacy Policy link presence and href
- Cookie Policy link presence and href
- Training Plan link presence and href
- External GitHub link functionality
- All links are accessible
Why It's Important
The footer provides essential links to legal pages and external resources. Broken footer links can cause compliance issues and frustrate users seeking information.
Manual Verification
Scroll to the bottom of any page. Verify: 1) Copyright shows current year, 2) All links are present and clickable, 3) Privacy Policy and Cookie Policy links work, 4) GitHub link opens in new tab.
Related Documentation
Home Page Component
__tests__/components/HomePage.test.tsx
Purpose
Tests the Home page component rendering and content
What It Tests
- Page renders without errors
- Main heading is present and accessible
- Primary content sections render correctly
- Call-to-action buttons are present
- Links to key pages work correctly
Why It's Important
The home page is the main entry point to the site. It must render correctly and guide users to important resources.
Manual Verification
Navigate to the home page (https://ffcadmin.org). Verify: 1) Page loads without errors, 2) All text and images display correctly, 3) All buttons and links are clickable, 4) Layout looks correct on mobile and desktop.
Related Documentation
Running Tests
For Developers: Local Testing
For Contributors: Before Committing
Always run the full quality check sequence before pushing code:
This matches the CI pipeline order and catches issues before they reach GitHub.
For Administrators: CI/CD Pipeline
Tests run automatically in GitHub Actions:
- On Pull Requests: All tests run before merge is allowed
- On Push to Main: Tests run before deployment to production
- After Deployment: Lighthouse CI runs performance audits
View test results in the GitHub Actions tab: Actions Dashboard
Understanding Test Results
✅ All Tests Passing
Everything is working correctly. Code quality standards are met and the application is ready for deployment.
❌ Test Failures
One or more tests failed. This indicates a problem that must be fixed before code can be merged. Common causes:
- Configuration file is missing or invalid
- Build output structure changed
- Component rendering failed
- Accessibility violations introduced
⚠️ Console Warnings
Tests pass but warnings are present (e.g., React act() warnings). These should be addressed but don't block deployment. They indicate potential issues that could cause problems later.
Additional Resources
Documentation
- TEST_CASES.md - Detailed test strategy
- CODE_QUALITY.md - Quality standards
- CONTRIBUTING.md - Development workflow
Testing Frameworks
- Jest - Test runner and assertions
- React Testing Library - Component testing
- jest-axe - Accessibility testing
Questions or issues with tests? Check our GitHub Issues or review the Documentation Center.