spec

Instruction file imported from untra/polyglot (.github/instructions/spec.instructions.md). Copyright stays with the author.

Test Suite Instructions

Test Organization

The test suite is organized to mirror the source code structure:

spec/jekyll/polyglot/              # Tests mirror lib/jekyll/polyglot/ structure
  hooks/
    coordinate_spec.rb             # Tests for document coordination
    polyglot_hook_spec.rb          # Tests for Jekyll hook registration
    subprocess_spec.rb             # Tests for parallel processing
  patches/jekyll/
    site_spec.rb                   # Tests for Jekyll::Site extensions
  sitemap_spec.rb                  # Tests for sitemap generation

spec/fixture/                      # Sample Jekyll sites for integration testing
  [fixture site directories]

Running Tests

# Run all tests with coverage
COVERAGE=true bundle exec rspec

# Run tests with verbose output
bundle exec rspec --format documentation

# Run a specific test file
bundle exec rspec spec/jekyll/polyglot/hooks/coordinate_spec.rb

# Run tests matching a pattern
bundle exec rspec --pattern "*coordinate*"

Writing Tests

When adding new features:

1. Create a test file in spec/jekyll/polyglot/ mirroring the source structure
2. Use RSpec conventions: describe, context, and it blocks
3. Test edge cases: Special characters, unicode, missing translations, empty inputs
4. Test integration: Use fixture Jekyll sites to test against realistic builds
5. Aim for >90% coverage: New code should maintain high coverage

Fixture Sites

The spec/fixture/ directory contains sample Jekyll sites used for integration testing:

• Use fixtures to test document coordination with multiple languages
• Test URL relativization with different permalink formats
• Test fallback behavior when translations are missing
• When adding complex features, consider adding a new fixture

Coverage Requirements

Coverage is tracked by Codecov with a target of 80% project coverage and 1% threshold tolerance:

• Run COVERAGE=true bundle exec rspec to generate coverage reports
• Reports are generated in coverage/ directory
• Coverage must not decrease; CI will reject PRs with lower coverage
• Aim for >90% on new modules

Common Assertions in Tests

• Document grouping: Verify documents with same permalink are grouped by language
• URL generation: Ensure URLs are correctly relativized for each language variant
• Fallback behavior: Verify missing content falls back to default language
• Configuration parsing: Test with various _config.yml configurations