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+

   # 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+

   cmake --version
   

3. Ninja Build System (recommended)

   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

# 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

# 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

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

# 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

# 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

# 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

# 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:

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

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

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

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

adb shell chmod +x /data/local/tmp/VavCoreUnitTests

Test Crashes on Device

Segmentation fault

Solution: Check logcat for stack trace

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

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:

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