libmagic-rs 0.5.0

A pure-Rust implementation of libmagic for file type identification
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145

# Compatibility Testing

This directory contains compatibility tests to ensure that libmagic-rs produces identical results to the original libmagic implementation.

## Overview

The compatibility test suite uses test files from the original [file/file](https://github.com/file/file) repository as a git submodule and runs our `rmagic` binary against each `.testfile` to verify that the output matches the corresponding `.result` file.

## Quick Start

### Initialize Test Files

```bash
# Initialize git submodule for test files from file/file repository
just download-compatibility-tests
```

### Run Compatibility Tests

```bash
# Run compatibility tests (requires test files to be downloaded)
just test-compatibility

# Run full compatibility test suite (initializes submodule and runs tests)
just test-compatibility-full
```

## Manual Usage

### Initialize Test Files

```bash
git submodule update --init --recursive tests/compatibility/file-tests
```

### Run Tests

```bash
# Build the project first
cargo build --release

# Run compatibility tests
cargo test test_compatibility_with_original_libmagic -- --ignored
```

## Test Structure

- `compatibility_tests.rs` - Rust test suite that runs compatibility tests
- `file-tests/` - Git submodule containing test files from file/file repository

## Test Files

The test files are downloaded to `tests/compatibility/file-tests/tests/` and include:

- `.testfile` - Test files to analyze
- `.result` - Expected output from original libmagic

## Output

The Rust test suite provides:

- Console output with test results and summary
- Detailed failure information for debugging
- Test status: PASS, FAIL, or ERROR

## CI/CD Integration

### GitHub Actions

The compatibility tests are automatically run on:

- Push to main/develop branches
- Pull requests
- Daily at 2 AM UTC

### Local Development

```bash
# Full compatibility test suite
just test-compatibility-full

# Just run tests (if files already downloaded)
just test-compatibility
```

## Troubleshooting

### Test Files Not Found

If you get "Test directory not found", run:

```bash
just download-compatibility-tests
```

### Binary Not Found

Ensure the project is built:

```bash
cargo build --release
```

### Magic File Not Found

Ensure the magic file exists at `third_party/magic.mgc`:

```bash
ls third_party/magic.mgc
```

## Test Results

The compatibility test runner provides:

- **PASS** - Output matches expected result exactly
- **FAIL** - Output differs from expected result
- **ERROR** - Test failed to run (binary error, file not found, etc.)

Failed tests show the expected vs actual output for debugging.

## Performance

The test suite typically runs in 30-60 seconds depending on the number of test files and system performance.

## Contributing

When adding new features to libmagic-rs:

1. Run the compatibility tests to ensure no regressions
2. If tests fail, investigate the differences
3. Update the implementation to match expected behavior
4. Re-run tests to verify fixes

## Test Coverage

The compatibility test suite covers:

- Basic file type detection
- Complex magic rules
- Edge cases and error conditions
- Various file formats and structures
- Performance characteristics

This ensures that libmagic-rs maintains full compatibility with the original libmagic implementation.