Testing

Testing practices and CI/CD pipeline for the Botnadzor Extension

The Botnadzor Extension uses automated testing and continuous integration to maintain code quality and catch issues early.

Unit Testing

Unit tests are written using Vitest, a fast unit test framework for Vite projects.

Running Unit Tests

Run all unit tests:

pnpm test:unit

This command runs the entire test suite and reports results.

Writing Tests

Tests should be placed alongside the code they test, using the .test.ts or .test.tsx extension:

src/
├── shared/
│   ├── formatting/
│   │   ├── format-int.ts
│   │   └── format-int.test.ts

Example test:

import { describe, expect, it } from 'vitest';
import { formatInt } from './format-int';

describe('formatInt', () => {
  it('formats integers with locale-specific separators', () => {
    expect(formatInt(1000)).toBe('1 000');
    expect(formatInt(1000000)).toBe('1 000 000');
  });

  it('handles negative numbers', () => {
    expect(formatInt(-1000)).toBe('-1 000');
  });
});

Linting

The project uses multiple linters to ensure code quality and consistency.

Run All Linters

Run all linting checks:

pnpm lint

This runs:

• ESLint - JavaScript/TypeScript linting
• Prettier - Code formatting
• TypeScript - Type checking
• knip - Unused file/export detection
• cspell - Spell checking
• pnpm dedupe - Dependency deduplication check

Auto-fix Issues

Many linting issues can be automatically fixed:

pnpm fix

This runs:

• pnpm fix:eslint - Fix ESLint issues
• pnpm fix:prettier - Format code with Prettier
• pnpm fix:knip - Remove unused files (with confirmation)
• pnpm fix:pnpm-dedupe - Deduplicate dependencies

Individual Linters

You can run individual linters for faster feedback:

ESLint

pnpm lint:eslint  # Check for issues
pnpm fix:eslint   # Auto-fix issues

Prettier

pnpm lint:prettier  # Check formatting
pnpm fix:prettier   # Format code

TypeScript

pnpm lint:tsc  # Type check

knip

pnpm lint:knip  # Find unused files/exports
pnpm fix:knip   # Remove unused (with confirmation)

cspell

pnpm lint:cspell  # Check spelling

If you encounter false positives, add words to cspell-words.txt.

pnpm dedupe

pnpm lint:pnpm-dedupe  # Check for duplicate dependencies
pnpm fix:pnpm-dedupe   # Deduplicate

CI/CD Pipeline

The project uses GitHub Actions for continuous integration and deployment.

When CI Runs

CI runs automatically on:

• Pull requests - All checks must pass before merging
• Push to main - Validates the main branch
• Tags - Triggers release builds

CI Jobs

The CI pipeline consists of two parallel jobs:

1. Build

Packages the extension for both browsers:

pnpm zip

This runs:

• pnpm build:chrome - Build Chrome extension
• pnpm build:firefox - Build Firefox extension
• Package both into .zip files

Artifacts:

• Chrome extension (.zip)
• Firefox extension (.zip)
• Source code archives (for tagged releases)

Retention:

• Pull requests: 2 days
• Main branch: 30 days
• Tagged releases: 90 days

2. Lint and Test

Runs all quality checks:

1. cspell - Spell checking
2. ESLint - Code linting
3. knip - Unused code detection
4. pnpm dedupe - Dependency deduplication
5. Prettier - Code formatting
6. TypeScript - Type checking
7. Vitest - Unit tests

All checks use if: ${{ success() || failure() }} to run independently, so you see all failures at once.

Local Pre-flight Check

Before pushing, run the same checks locally:

pnpm lint       # All linters
pnpm test:unit  # Unit tests

Fix issues automatically where possible:

pnpm fix

CI Failure Messages

When CI fails, you’ll see helpful messages:

For auto-fixable issues (ESLint, Prettier, knip):

ℹ️ ℹ️ ℹ️
Try running `pnpm fix:eslint` locally to apply autofixes.
ℹ️ ℹ️ ℹ️

For manual fixes (TypeScript, tests, cspell):

ℹ️ ℹ️ ℹ️
Please fix the above errors locally for the check to pass.
If you don't see them, try merging target branch into yours.
ℹ️ ℹ️ ℹ️

For dependency deduplication:

ℹ️ ℹ️ ℹ️
Some dependencies can be deduplicated, which will make pnpm-lock.yaml
lighter and potentially save us from unexplainable bugs.
Please run `pnpm fix:pnpm-dedupe` locally and commit pnpm-lock.yaml.
ℹ️ ℹ️ ℹ️

Development Scripts

Complete list of development commands:

Building

pnpm build         # Build for Chrome + Firefox
pnpm build:chrome  # Build Chrome only
pnpm build:firefox # Build Firefox only
pnpm zip           # Build and package both

Development Server

pnpm dev:chrome   # Chrome with hot reload
pnpm dev:firefox  # Firefox with hot reload

Testing

pnpm test:unit  # Run unit tests

Linting

pnpm lint               # All linters
pnpm lint:cspell        # Spell checking
pnpm lint:eslint        # JavaScript/TypeScript linting
pnpm lint:knip          # Unused code detection
pnpm lint:pnpm-dedupe   # Dependency deduplication check
pnpm lint:prettier      # Code formatting check
pnpm lint:tsc           # TypeScript type checking

Auto-fixing

pnpm fix               # All auto-fixes
pnpm fix:eslint        # Fix ESLint issues
pnpm fix:knip          # Remove unused files
pnpm fix:pnpm-dedupe   # Deduplicate dependencies
pnpm fix:prettier      # Format code

Pre-commit Hooks

The project uses Husky with lint-staged to run checks before commits.

Automatically runs on commit:

• Prettier formatting on staged files

This ensures that committed code is always properly formatted.

Best Practices

Run linters before pushing

Always run pnpm lint locally before pushing to catch issues early:

pnpm lint && git push

Use pnpm fix for quick fixes

Many issues can be fixed automatically. Run pnpm fix first:

pnpm fix  # Auto-fix what can be fixed
pnpm lint # Check remaining issues

Test in both browsers

Always test your changes in both Chrome and Firefox:

pnpm dev:chrome   # Test in Chrome
pnpm dev:firefox  # Test in Firefox

Write tests for new features

Add unit tests for new functionality:

// my-feature.ts
export function myFeature() { /* ... */ }

// my-feature.test.ts
import { describe, expect, it } from 'vitest';
import { myFeature } from './my-feature';

describe('myFeature', () => {
  it('does what it should', () => {
    expect(myFeature()).toBe(expected);
  });
});

Keep dependencies deduplicated

Run pnpm dedupe periodically to keep pnpm-lock.yaml lean:

pnpm fix:pnpm-dedupe

Related Documentation

• Code Conventions - Coding standards and patterns
• Contributing Guide - How to contribute
• CI Workflow - Full CI configuration