cambria

Fossil Version Control: Test Suite Documentation
Login

This document catalogs the test suite for Fossil's version control system core, excluding UI, web, wiki, forum, and ticket features. Tests are organized in an order suitable for implementing a version control system from basic to complex features, ensuring each test builds upon previously tested functionality.

Test Organization Philosophy

Tests are ordered to support incremental implementation:

  1. Foundation: Delta compression, file operations, basic data structures
  2. Core Operations: Repository initialization, adding files, committing
  3. Basic Version Control: Checkout, update, status, diff
  4. File Management: Move, rename, remove operations
  5. Branching & Tagging: Branch creation, tag management
  6. Advanced Operations: Merging, conflict resolution, cherry-pick
  7. State Management: Stash, revert, undo
  8. Repository Operations: Rebuild, integrity checks
  9. Distributed Operations: Clone, sync, push, pull (if present)

Phase 1: Foundation & Core Algorithms

1.1 Delta Compression (delta1.test)

Purpose: Tests the delta compression algorithm which is fundamental to efficient storage.

Description: Validates delta creation and application by:

Acceptance Criteria:

Dependencies: None (most basic building block)

Relevant Schema: delta(rid, srcid), blob.content

Relevant Modules: src/delta.c, src/content.c


1.2 File Path Operations (file1.test)

Purpose: Tests file path manipulation utilities essential for working tree operations.

Description: Validates path simplification and relative/absolute path resolution:

Acceptance Criteria:

Dependencies: None

Relevant Schema: filename(fnid, name)

Relevant Modules: src/file.c, src/filename.c


1.3 Glob Pattern Matching (glob.test)

Purpose: Tests pattern matching for file selection operations.

Description: Validates glob pattern parsing and matching:

Acceptance Criteria:

Dependencies: None

Relevant Modules: src/glob.c


Phase 2: Repository & Commit Operations

2.1 Binary File Detection & Diff Basics (diff.test)

Purpose: Tests binary file detection and basic diff operations.

Description: Validates the system's ability to:

Acceptance Criteria:

Dependencies: Delta compression

Relevant Schema: blob.content, mlink

Relevant Modules: src/diff.c, src/diffcmd.c


2.2 Commit Warnings (commit-warning.test)

Purpose: Tests pre-commit validation and warnings for file characteristics.

Description: Validates detection and warnings for:

Acceptance Criteria:

Dependencies: File operations, diff basics

Relevant Modules: src/checkin.c, src/encode.c


2.3 Basic Add/Commit Cycle (mv-rm.test - setup section)

Purpose: Tests the fundamental add and commit operations.

Description: Validates initial repository operations:

Acceptance Criteria:

Dependencies: File operations, delta compression

Relevant Schema: blob, mlink, plink, filename, event

Relevant Modules: src/checkin.c, src/manifest.c, src/add.c


2.4 File Lifecycle - Add/Extra/Changes (clean.test - setup)

Purpose: Tests file status determination and working copy queries.

Description: Validates the system's ability to:

Acceptance Criteria:

Dependencies: Add/commit cycle

Relevant Schema: vfile (working copy virtual table), blob, mlink

Relevant Modules: src/checkin.c, src/vfile.c


Phase 3: Checkout & Update Operations

3.1 Basic Checkout (update.test - initial state)

Purpose: Tests checking out repository content to working directory.

Description: Validates:

Acceptance Criteria:

Dependencies: Add/commit cycle, delta compression

Relevant Schema: mlink, blob, delta, filename

Relevant Modules: src/checkout.c, src/content.c, src/vfile.c


3.2 Update Operations (update.test)

Purpose: Comprehensive test of update scenarios between versions.

Description: Tests all update scenarios:

Acceptance Criteria:

Dependencies: Checkout, diff, file status

Relevant Schema: mlink, plink, vfile, blob

Relevant Modules: src/checkout.c, src/update.c, src/merge.c


Phase 4: File Management Operations

4.1 Move/Rename Operations (mv-rm.test - move tests)

Purpose: Tests file and directory renaming operations.

Description: Validates both soft (metadata only) and hard (filesystem) operations:

Acceptance Criteria:

Dependencies: Add/commit, file operations

Relevant Schema: mlink.pfnid (parent filename for renames), filename

Relevant Modules: src/mv.c, src/checkin.c


4.2 Remove Operations (mv-rm.test - remove tests)

Purpose: Tests file and directory removal from version control.

Description: Validates soft and hard remove operations:

Acceptance Criteria:

Dependencies: Add/commit, move operations

Relevant Schema: mlink, vfile

Relevant Modules: src/rm.c, src/checkin.c


4.3 Clean Operations (clean.test)

Purpose: Tests removal of unmanaged files from working directory.

Description: Validates cleaning extra files:

Acceptance Criteria:

Dependencies: File lifecycle tracking

Relevant Modules: src/clean.c, src/undo.c


Phase 5: Three-Way Merge Foundation

5.1 Basic Three-Way Merge (merge1.test)

Purpose: Tests fundamental three-way merge algorithm.

Description: Tests merge scenarios with common ancestor:

Acceptance Criteria:

Dependencies: Diff, file operations

Relevant Schema: N/A (algorithm test using fossil 3-way-merge utility)

Relevant Modules: src/merge.c, src/diff.c


5.2 Random Merge Testing (merge2.test)

Purpose: Stress tests merge algorithm with random changes.

Description: Applies random modifications and verifies:

Acceptance Criteria:

Dependencies: Basic three-way merge

Relevant Modules: src/merge.c, src/diff.c


5.3 Complex Merge Scenarios (merge3.test)

Purpose: Tests merge algorithm on carefully crafted edge cases.

Description: Tests specific problematic scenarios:

Acceptance Criteria:

Dependencies: Basic three-way merge

Relevant Modules: src/merge.c, src/diff.c


5.4 Bidirectional Merge Testing (merge4.test)

Purpose: Tests merge symmetry and bidirectional properties.

Description: Validates that merging A→B and B→A produces consistent results:

Acceptance Criteria:

Dependencies: Complex merge scenarios

Relevant Modules: src/merge.c, src/diff.c


Phase 6: Repository-Level Merge Operations

6.1 Branch-Level Merge (merge5.test)

Purpose: Tests merging entire branches with file-level integration.

Description: Tests repository-level merge operations:

Acceptance Criteria:

Dependencies: Three-way merge, checkout/update, commit

Relevant Schema: plink, mlink, blob, leaf

Relevant Modules: src/merge.c, src/checkin.c, src/manifest.c


6.2 Multiple Merge Sources (merge6.test)

Purpose: Tests merging multiple branches sequentially.

Description: Validates:

Acceptance Criteria:

Dependencies: Branch-level merge

Relevant Schema: plink.isprim (primary vs secondary parents), cherrypick

Relevant Modules: src/merge.c, src/checkin.c


6.3 Merge with Renames (merge_renames.test)

Purpose: Tests merging when files have been renamed.

Description: Tests complex scenarios:

Acceptance Criteria:

Dependencies: Move operations, branch-level merge

Relevant Schema: mlink.pfnid, mlink.pid (parent file ID for renames)

Relevant Modules: src/merge.c, src/manifest.c, src/checkin.c


6.4 Additional Rename Merge Cases (merge_renames_2.test)

Purpose: Tests additional rename merge edge cases.

Description: Further validates:

Acceptance Criteria:

Dependencies: Merge with renames

Relevant Modules: src/merge.c, src/branch.c


6.5 Executable File Merging (merge_exe.test)

Purpose: Tests merging files with executable permissions.

Description: Validates permission handling in merges:

Acceptance Criteria:

Dependencies: Branch-level merge

Relevant Schema: mlink.mperm (file permissions)

Relevant Modules: src/merge.c, src/checkin.c


6.6 Merge Warnings (merge_warn.test)

Purpose: Tests warning generation during merge operations.

Description: Validates warnings for:

Acceptance Criteria:

Dependencies: Branch-level merge

Relevant Modules: src/merge.c


Phase 7: State Management Operations

7.1 Revert Operations (revert.test)

Purpose: Tests reverting working directory changes.

Description: Validates reverting various change types:

Acceptance Criteria:

Dependencies: Add, remove, move, modify operations

Relevant Schema: vfile

Relevant Modules: src/revert.c, src/undo.c


7.2 Stash Operations (stash.test)

Purpose: Tests stashing and restoring working directory changes.

Description: Validates stash functionality:

Acceptance Criteria:

Dependencies: Revert, add/remove/move/modify operations

Relevant Schema: Private blob storage for stash artifacts

Relevant Modules: src/stash.c, src/undo.c


Phase 8: Branch & Tag Management

8.1 Branch Creation & Management (amend.test - branch section)

Purpose: Tests branch creation and manipulation.

Description: Validates:

Acceptance Criteria:

Dependencies: Commit operations, checkout

Relevant Schema: tag, tagxref (branch is a tag), leaf

Relevant Modules: src/branch.c, src/tag.c, src/checkin.c


8.2 Tag Operations (amend.test - tag section)

Purpose: Tests tagging and tag manipulation.

Description: Validates:

Acceptance Criteria:

Dependencies: Commit operations

Relevant Schema: tag, tagxref

Relevant Modules: src/tag.c, src/checkin.c


8.3 Commit Amendments (amend.test)

Purpose: Tests amending historical commits.

Description: Validates amending:

Acceptance Criteria:

Dependencies: Commit operations, tag operations

Relevant Schema: blob (control artifacts), event

Relevant Modules: src/amend.c, src/tag.c


Phase 9: Advanced Features

9.1 Manifest Operations (set-manifest.test)

Purpose: Tests manifest file generation and validation.

Description: Validates:

Acceptance Criteria:

Dependencies: Commit operations, rename operations

Relevant Schema: blob (manifest artifacts), mlink

Relevant Modules: src/manifest.c, src/checkin.c


9.2 Reserved Names Handling (reserved-names.test)

Purpose: Tests handling of filesystem reserved names.

Description: Validates behavior with:

Acceptance Criteria:

Dependencies: File operations, commit operations

Relevant Modules: src/file.c, src/checkin.c


9.3 Symbolic Link Handling (symlinks.test)

Purpose: Tests version control of symbolic links.

Description: Validates:

Acceptance Criteria:

Dependencies: Add/commit, checkout

Relevant Schema: mlink.mperm (symlink permission bit)

Relevant Modules: src/checkin.c, src/checkout.c, src/file.c


9.4 UTF-8 Handling (utf.test)

Purpose: Tests UTF-8 encoding in filenames and content.

Description: Validates:

Acceptance Criteria:

Dependencies: Basic operations (add/commit/checkout)

Relevant Modules: src/encode.c, all file I/O modules


Phase 10: Repository Integrity & Maintenance

10.1 Repository Settings (settings-repo.test)

Purpose: Tests repository-specific settings.

Description: Validates:

Acceptance Criteria:

Dependencies: Commit operations

Relevant Schema: config table, versioned files

Relevant Modules: src/configure.c, src/db.c


10.2 Unversioned File Operations (unversioned.test)

Purpose: Tests unversioned file storage and retrieval.

Description: Validates:

Acceptance Criteria:

Dependencies: Basic repository operations

Relevant Schema: unversioned table

Relevant Modules: src/unversioned.c


Phase 11: Distributed Operations (If Implemented)

Note: The test suite examined focuses primarily on local repository operations. Full sync/clone/push/pull tests may exist in separate integration tests or may be tested manually.

11.1 Clone Operations (Not found in examined tests)

Purpose: Tests repository cloning.

Expected Coverage:

Relevant Schema: rcvfrom, blob.rcvid

Relevant Modules: src/clone.c, src/xfer.c


11.2 Sync Operations (Not found in examined tests)

Purpose: Tests bidirectional synchronization.

Expected Coverage:

Relevant Schema: rcvfrom, unsent, phantom, private

Relevant Modules: src/sync.c, src/xfer.c


Test Execution Framework

Test Infrastructure (tester.tcl)

Purpose: Provides test harness and utilities.

Key Features:

Common Utilities:


Implementation Priority Summary

For implementing a compatible VCS, tests should be executed in this order:

  1. Foundation (Phase 1): Delta, file ops, glob → Enables storage layer
  2. Core VCS (Phase 2-3): Add, commit, checkout, update → Basic VCS workflow
  3. File Management (Phase 4): Move, remove, clean → Complete file lifecycle
  4. Merge Foundation (Phase 5): Three-way merge algorithm → Enables branching
  5. Repository Merge (Phase 6): Branch merges, renames → Full merge support
  6. State Management (Phase 7): Revert, stash → Developer workflow tools
  7. Branch/Tag (Phase 8): Branch creation, tagging, amendments → Version management
  8. Advanced (Phase 9): Manifests, symlinks, UTF-8, reserved names → Edge cases
  9. Integrity (Phase 10): Settings, unversioned files → Repository maintenance
  10. Distributed (Phase 11): Clone, sync → Multi-repository collaboration

Each phase builds upon previous phases, ensuring that dependencies are satisfied before testing more complex features.


Test Coverage Metrics

Component Test Files Focus Areas
Delta Compression delta1.test Algorithm correctness
File Operations file1.test, glob.test Path manipulation, pattern matching
Diff & Merge diff.test, merge1-6.test, merge3-4.test, merge_renames*.test, merge_exe.test, merge_warn.test All merge scenarios
Checkout/Update update.test State transitions
File Lifecycle mv-rm.test, clean.test, revert.test Move, remove, revert operations
Stash stash.test Temporary state storage
Commit commit-warning.test, amend.test Commit creation and modification
Advanced set-manifest.test, reserved-names.test, symlinks.test, utf.test Edge cases
Repository settings-repo.test, unversioned.test Configuration and maintenance

Total Test Categories: 9 major areas Total Test Files Analyzed: ~25 files Test Approach: Mix of unit tests (algorithm tests) and integration tests (full workflow tests)


Cross-Reference: Tests to Schema/Modules

Schema Element Primary Test Files
blob, delta delta1.test, all merge tests
filename file1.test, mv-rm.test
mlink, plink merge5.test, merge_renames*.test, amend.test
leaf amend.test, merge5.test
tag, tagxref amend.test
event amend.test, commit tests
vfile update.test, revert.test, stash.test
Module Primary Test Files
src/delta.c delta1.test
src/merge.c merge1.test through merge_warn.test
src/checkin.c All commit-related tests
src/checkout.c update.test, merge tests
src/manifest.c set-manifest.test, merge tests
src/mv.c, src/rm.c mv-rm.test
src/revert.c revert.test
src/stash.c stash.test
src/tag.c, src/branch.c amend.test

Conclusion

This test suite provides comprehensive coverage of Fossil's version control core, focusing on correctness of fundamental algorithms (delta, merge), robustness of file operations (add, move, remove, rename), and completeness of version control workflows (commit, branch, merge, revert). The tests are structured to support incremental implementation, with each phase building on the previous, ensuring a solid foundation before tackling complex features like merge conflict resolution and distributed synchronization.