video-v1/vav2/platforms/android/tests/unit-tests/README.md

# VavCore Android Unit Tests

Comprehensive unit tests for VavCore Android MediaCodec implementation using Google Test framework.

## Overview

This test suite validates the core functionality of VavCore's Android components:

- **MediaCodecAV1Decoder**: Hardware-accelerated AV1 decoding via Android MediaCodec
- **WebMFileReader**: WebM/MKV file parsing and packet extraction
- **MediaCodecSelector**: Codec selection and hardware capability detection
- **VideoDecoderFactory**: Decoder instantiation and management

## Test Coverage

### MediaCodecAV1Decoder Tests (12 tests)
- ✅ Basic initialization and cleanup
- ✅ Get available codecs
- ✅ Initialize with valid/invalid metadata
- ✅ Decode frame without initialization (error handling)
- ✅ Reset and flush functionality
- ✅ Decoder statistics
- ✅ Multiple initialize/cleanup cycles
- ✅ Codec type support
- ✅ Hardware acceleration detection

### WebMFileReader Tests (15 tests)
- ✅ File open/close operations
- ✅ Error handling (null path, empty path, non-existent file)
- ✅ Video track enumeration
- ✅ Packet reading
- ✅ File duration extraction
- ✅ Seek operations
- ✅ Reset and re-read
- ✅ Multiple close calls (safety)

### MediaCodecSelector Tests (10 tests)
- ✅ Get available AV1 codecs
- ✅ Best codec selection
- ✅ Keyword-based priority (hardware first)
- ✅ Empty codec list handling
- ✅ Hardware acceleration check
- ✅ Codec capabilities retrieval
- ✅ 4K resolution support
- ✅ Resolution-based filtering
- ✅ Qualcomm codec priority verification

### VideoDecoderFactory Tests (14 tests)
- ✅ Factory initialization
- ✅ Get available decoders
- ✅ Create decoder by type (AUTO, MEDIACODEC, DAV1D)
- ✅ Create decoder by name
- ✅ Create decoder from codec ID
- ✅ Codec support checking
- ✅ Decoder descriptions
- ✅ Priority ordering
- ✅ Concurrent decoder creation
- ✅ Factory cleanup and reinitialization
- ✅ Invalid decoder type handling

**Total: 51 comprehensive tests**

## Prerequisites

### Required Software

1. **Android NDK r25+**
   ```bash
   # Set environment variable
   export ANDROID_NDK_HOME=/path/to/android-ndk-r25
   # or
   export ANDROID_NDK_ROOT=/path/to/android-ndk-r25
   ```

2. **CMake 3.18.1+**
   ```bash
   cmake --version
   ```

3. **Ninja Build System** (recommended)
   ```bash
   ninja --version
   ```

4. **Android Device or Emulator**
   - API Level 29+ (Android 10+)
   - ARM64 or ARM32 architecture
   - Hardware AV1 decoder (recommended but not required)

### Required Libraries

These are automatically linked by CMakeLists.txt:
- Google Test (automatically downloaded via FetchContent)
- VavCore source files
- Android MediaCodec NDK library
- Android log library
- dav1d library (for fallback)
- libwebm library (for WebM parsing)

## Building Tests

### On Windows

```batch
# Build for ARM64 (default)
cd D:\Project\video-av1\vav2\platforms\android\tests\unit-tests
build.bat

# Build for ARM32
build.bat Debug armeabi-v7a

# Build Release version
build.bat Release arm64-v8a
```

### On Linux/macOS

```bash
# Build for ARM64 (default)
cd /path/to/vav2/platforms/android/tests/unit-tests
chmod +x build.sh
./build.sh

# Build for ARM32
./build.sh Debug armeabi-v7a

# Build Release version
./build.sh Release arm64-v8a
```

### Manual CMake Build

```bash
mkdir -p build-arm64-v8a
cd build-arm64-v8a

cmake .. \
    -DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake \
    -DANDROID_ABI=arm64-v8a \
    -DANDROID_NATIVE_API_LEVEL=29 \
    -DCMAKE_BUILD_TYPE=Debug \
    -G Ninja

cmake --build .
```

## Running Tests

### Push to Device

```bash
# Push test executable
adb push build-arm64-v8a/VavCoreUnitTests /data/local/tmp/

# Make executable
adb shell chmod +x /data/local/tmp/VavCoreUnitTests
```

### Run All Tests

```bash
# Run all tests
adb shell /data/local/tmp/VavCoreUnitTests

# View output with logcat
adb logcat -c  # Clear log
adb shell /data/local/tmp/VavCoreUnitTests &
adb logcat | grep -E "VavCore|gtest"
```

### Run Specific Tests

```bash
# Run only MediaCodec tests
adb shell /data/local/tmp/VavCoreUnitTests --gtest_filter="MediaCodecAV1DecoderTest.*"

# Run only WebM tests
adb shell /data/local/tmp/VavCoreUnitTests --gtest_filter="WebMFileReaderTest.*"

# Run specific test case
adb shell /data/local/tmp/VavCoreUnitTests --gtest_filter="MediaCodecAV1DecoderTest.GetAvailableCodecs"
```

### Google Test Options

```bash
# List all tests
adb shell /data/local/tmp/VavCoreUnitTests --gtest_list_tests

# Repeat tests 10 times
adb shell /data/local/tmp/VavCoreUnitTests --gtest_repeat=10

# Shuffle test order
adb shell /data/local/tmp/VavCoreUnitTests --gtest_shuffle

# Generate XML output
adb shell /data/local/tmp/VavCoreUnitTests --gtest_output=xml:/data/local/tmp/test_results.xml
adb pull /data/local/tmp/test_results.xml
```

## Test File Requirements

Some tests require actual WebM/AV1 video files. Place test files at:

```
/sdcard/Download/test_video.webm
```

Or modify the test file path in `WebMFileReaderTest.cpp`:

```cpp
const char* testFile = "/your/custom/path/test_video.webm";
```

Tests will automatically skip if test files are not available.

## Interpreting Results

### Success Output

```
[==========] Running 51 tests from 4 test suites.
[----------] Global test environment set-up.
[----------] 12 tests from MediaCodecAV1DecoderTest
[ RUN      ] MediaCodecAV1DecoderTest.InitializationAndCleanup
[       OK ] MediaCodecAV1DecoderTest.InitializationAndCleanup (5 ms)
...
[==========] 51 tests from 4 test suites ran. (1234 ms total)
[  PASSED  ] 51 tests.
```

### Skipped Tests

```
[  SKIPPED ] MediaCodecAV1DecoderTest.InitializeWithValidMetadata
Reason: No AV1 codecs available on this device (API < 29 or no hardware support)
```

This is normal on:
- Emulators without AV1 support
- Devices with API level < 29
- Devices without hardware AV1 decoder

### Failed Tests

```
[  FAILED  ] MediaCodecAV1DecoderTest.GetAvailableCodecs
Expected: codecs.size() >= 1
Actual: 0
```

Investigate:
1. Check device AV1 support: `adb shell dumpsys media.codec_list | grep av01`
2. Check API level: `adb shell getprop ro.build.version.sdk`
3. Review logcat for detailed error messages

## Troubleshooting

### NDK Not Found

```
Error: ANDROID_NDK_HOME or ANDROID_NDK_ROOT must be set
```

**Solution**: Set environment variable
```bash
export ANDROID_NDK_HOME=/path/to/android-ndk-r25
```

### CMake Configuration Failed

```
CMake Error: Android toolchain file not found
```

**Solution**: Verify NDK path and CMake version
```bash
ls "$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake"
cmake --version  # Should be 3.18.1+
```

### Build Errors: Missing Libraries

```
ld.lld: error: unable to find library -ldav1d
```

**Solution**: Build VavCore dependencies first
```bash
cd D:\Project\video-av1\vav2\platforms\android\vavcore
./build_vavcore_android.bat arm64
```

### Test Execution Failed: Permission Denied

```
/data/local/tmp/VavCoreUnitTests: Permission denied
```

**Solution**: Make executable
```bash
adb shell chmod +x /data/local/tmp/VavCoreUnitTests
```

### Test Crashes on Device

```
Segmentation fault
```

**Solution**: Check logcat for stack trace
```bash
adb logcat -d | grep -A 50 "FATAL EXCEPTION"
```

Common causes:
- Missing library dependencies
- Incompatible ABI (wrong ARM32/ARM64)
- NULL pointer dereference (check test logs)

## Continuous Integration

### GitHub Actions Example

```yaml
name: Android Unit Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Set up NDK
        uses: nttld/setup-ndk@v1
        with:
          ndk-version: r25c
      - name: Build tests
        run: |
          cd vav2/platforms/android/tests/unit-tests
          ./build.sh Release arm64-v8a
      - name: Upload test binary
        uses: actions/upload-artifact@v2
        with:
          name: unit-tests
          path: vav2/platforms/android/tests/unit-tests/build-arm64-v8a/VavCoreUnitTests
```

## Contributing

When adding new tests:

1. Follow existing test structure and naming conventions
2. Use `LOGI` for informational logs
3. Use `EXPECT_*` for non-critical assertions
4. Use `ASSERT_*` for critical assertions
5. Use `GTEST_SKIP()` for conditional tests (e.g., hardware-dependent)
6. Include descriptive success messages

Example:
```cpp
TEST_F(MyComponentTest, MyTestCase) {
    LOGI("Test: MyTestCase");

    auto result = component->DoSomething();

    EXPECT_TRUE(result) << "DoSomething should succeed";

    if (result) {
        SUCCEED() << "Test passed with expected behavior";
    } else {
        GTEST_SKIP() << "Feature not available on this device";
    }
}
```

## License

Part of VavCore AV1 Video Player project.

---

**Last Updated**: 2025-09-30
**Maintainer**: VavCore Development Team