Automated Testing

Why Automated Testing?

Nobody likes when software is broken, but it's a really unpleasant feeling to know you broke the software for others. As a first line of defense against broken software, ChurchCRM uses automated, browser-based testing. We've developed a set of scripts that emulate a real user by clicking and typing in strategic locations within the application to ensure that all features work as intended.

We've automated testing of critical functionality. This way, components are tested every time any code is changed.

Details

There are many different automated testing strategies (unit testing, integration testing, etc). As ChurchCRM matures, so will our testing strategies; however, we're currently focused on end-to-end (E2E) browser automation testing. This form of testing gives us the largest amount of code coverage for the smallest amount of testing code.

Toolset

• Cypress Cypress is a modern end-to-end testing framework that provides fast, reliable, and easy-to-debug tests. It runs tests directly in the browser and provides excellent developer experience with time-travel debugging and real-time reloads.

• Docker Docker containers provide consistent testing environments across development and CI/CD pipelines, ensuring tests run the same way everywhere.

• JavaScript/TypeScript Tests are written in JavaScript/TypeScript, making them accessible to frontend developers and providing excellent IDE support with autocompletion and type checking.

Tests

End-to-End Tests

ChurchCRM uses Cypress for comprehensive end-to-end testing that validates complete user workflows.

Running Cypress Tests

Option 1: Using Docker (Recommended)

# Start the testing environment
npm run docker:test:start

# Run all tests in headless mode
npm run test

# Run tests in interactive UI mode (for development/debugging)
npm run docker:test:ui

# Stop the testing environment  
npm run docker:test:stop

Option 2: Local Development

# Start development environment
npm run docker:dev:start

# Run tests in interactive mode (for test development)
npx cypress open

# Run tests in headless mode
npx cypress run

Test Structure

Tests are organized in the cypress/e2e/ directory:

cypress/e2e/
├── api/           # API endpoint tests
├── ui/            # User interface tests
│   ├── admin/     # Admin functionality tests
│   ├── people/    # People management tests
│   ├── families/  # Family management tests
│   └── guest/     # Guest/public access tests
└── xReset/        # Database reset tests

Writing Cypress Tests

Cypress tests are written in JavaScript/TypeScript using a fluent API:

describe('People Management', () => {
  it('should create a new person', () => {
    cy.loginStandard('PersonEditor.php');
    
    cy.get('#FirstName').type('John');
    cy.get('#LastName').type('Doe');
    cy.get('#Email').type('[email protected]');
    
    cy.get('.btn-success').click();
    
    cy.url().should('contain', 'PersonView.php');
    cy.contains('John Doe');
  });
});

Custom Commands

ChurchCRM provides custom Cypress commands for common operations:

// Login as admin user
cy.loginAdmin();

// Login as standard user and navigate to page
cy.loginStandard('PersonEditor.php');

// API operations
cy.createFamily();
cy.createPerson();

Test Categories

UI Tests

• Admin Tests: Administrative functionality, system settings, user management
• People Tests: Person creation, editing, and management
• Family Tests: Family management and relationships
• Guest Tests: Public-facing features and registration

API Tests

• CRUD Operations: Create, read, update, delete operations for all entities
• Authentication: Login, logout, and permission testing
• Data Validation: Input validation and error handling

Best Practices

1. Use Data Attributes: Target elements using data-cy attributes for stability
2. Clean State: Each test should start with a clean, predictable state
3. Descriptive Names: Use clear, descriptive test and describe block names
4. Page Objects: Use page object pattern for complex interactions
5. Wait Strategies: Use Cypress's built-in retry-ability instead of hard waits

Debugging Tests

Cypress provides excellent debugging capabilities:

• Time Travel: Click on commands in the test runner to see application state
• Console Output: Use cy.log() and browser dev tools for debugging
• Screenshots: Automatic screenshots on test failures
• Video Recording: Full test run videos for CI environments

Continuous Integration

Tests run automatically on:

• Pull request creation and updates
• Commits to main branch
• Scheduled daily runs

View test results in the GitHub Actions tab of the repository.

Useful Resources

• Cypress Documentation
• Cypress Best Practices
• Writing Your First Test
• Custom Commands
• ChurchCRM Test Examples