테스트 모음을 사용한 스크린샷 테스트

Android Gradle 플러그인 (AGP) 9.5.0-alpha03 및 Compose 미리보기 스크린샷 테스트 엔진 0.0.1-alpha16부터 스크린샷 테스트가 AGP의 네이티브 테스트 모음 프레임워크와 통합됩니다.

이 접근 방식은 독립형 스크린샷 플러그인(com.android.compose.screenshot)을 대체합니다. 다음과 같은 이유로 AGP 테스트 모음을 채택하는 것이 좋습니다.

• 네이티브 Gradle 작업 수명 주기: 스크린샷 테스트가 표준 Gradle 및 AGP 테스트 수명 주기에 직접 통합되어 작업 격리 및 테스트 실행 안정성이 개선됩니다.
• 다양한 변형 및 맞춤 모음 지원: 사전 구성된 단일 소스 세트로 제한되지 않고 단일 모듈 내에서 여러 개의 개별 스크린샷 테스트 모음 (예: screenshotTest, uiTests, smokeTests)을 만들고 특정 빌드 변형(예: demoDebug, release)을 타겟팅할 수 있습니다.
• 빌드 성능 및 격리 향상: AGP 테스트 모음은 내장 아티팩트 변환 (예: Layoutlib 런타임 추출) 및 격리된 클래스 로딩을 사용하며 Gradle 구성 캐싱 및 프로젝트 격리를 완전히 지원합니다.

요구사항

테스트 모음과 함께 Compose 스크린샷 테스트를 사용하려면 환경이 다음 요구사항을 충족해야 합니다.

• Android 스튜디오 Rabbit 1 Canary 4 이상
• Android Gradle 플러그인 (AGP) 버전 9.5.0-alpha03 이상
• Compose 스크린샷 엔진 버전 0.0.1-alpha16 이상
• JDK 버전 17 이상
• 프로젝트에 Compose가 사용 설정되어 있습니다. Compose 컴파일러 Gradle 플러그인을 사용하여 Compose를 사용 설정하는 것이 좋습니다.

설정 및 구성

테스트 모음으로 Compose 스크린샷 테스트를 구성하려면 다음 단계를 완료하세요.

1. 실험용 플래그 사용 설정

프로젝트의 루트 gradle.properties 파일에서 스크린샷 테스트와 테스트 모음 지원을 사용 설정합니다.

android.experimental.enableScreenshotTest=true
android.experimental.testSuiteSupport=true

2. build.gradle.kts 파일에서 테스트 모음 구성

모듈의 build.gradle.kts 파일에서 testOptions 블록 내에 스크린샷 테스트 모음을 정의합니다.

android {
    testOptions {
        screenshotTests.create("screenshotTest") { // suiteName can be customized (for example, "uiTests")
            engineVersion = "0.0.1-alpha16"
            targetVariants.add("demoDebug") // Add specific variants to test

            dependencies {
                implementation(libs.androidx.compose.ui.tooling)
                implementation("com.android.tools.screenshot:screenshot-validation-api:0.0.1-alpha16")
            }
        }
    }
}

3. 테스트 소스 세트 만들기

스위트 이름과 일치하는 전용 소스 세트 디렉터리를 만듭니다.

{module}/src/{suiteName}/kotlin/

예를 들어 이름이 screenshotTest인 스위트의 경우 다음을 실행합니다.

feature/foryou/impl/src/screenshotTest/kotlin/com/example/app/ForYouScreenTest.kt

4. 컴포저블 미리보기 테스트 정의

@PreviewTest 및 표준 @Preview 또는 다중 미리보기 주석으로 컴포저블에 주석을 답니다.

package com.example.app

import androidx.compose.runtime.Composable
import androidx.compose.ui.tooling.preview.Preview
import com.android.tools.screenshot.PreviewTest
import com.example.app.ui.theme.AppTheme

@PreviewTest
@Preview(showBackground = true)
@Composable
fun ForYouScreenPreview() {
    AppTheme {
        ForYouScreen(isSyncing = false)
    }
}

스크린샷 테스트 실행

AGP 테스트 모음은 모음 이름, 타겟, 변형을 기반으로 전용 Gradle 작업을 생성합니다.

1. 참조 이미지 생성 또는 업데이트

컴포저블 미리보기를 렌더링하고 골든 기준 참조 이미지를 저장합니다.

• Linux 및 macOS: ./gradlew update{SuiteName}{Target}{Variant}TestSuite (예: ./gradlew updateScreenshotTestDefaultDemoDebugTestSuite)
• Windows: gradlew updateScreenshotTestDefaultDemoDebugTestSuite

참조 이미지가 다음 위치에 생성되고 저장됩니다.

{module}/src/{suiteName}{Target}{Variant}/reference/

2. 테스트 확인 및 실행

새 스크린샷을 렌더링하고 참조 이미지와 비교합니다.

• Linux 및 macOS: ./gradlew test{SuiteName}{Target}{Variant}TestSuite (예: ./gradlew testScreenshotTestDefaultDemoDebugTestSuite)
• Windows: gradlew testScreenshotTestDefaultDemoDebugTestSuite

테스트 보고서 검사

차이가 감지되거나 테스트가 실패하면 AGP에서 HTML 테스트 보고서를 생성합니다.

• 보고서 위치: {module}/build/reports/tests/{taskName}/index.html (예: app/build/reports/tests/testScreenshotTestDefaultDemoDebugTestSuite/index.html)

업데이트된 보고서에는 다음이 포함됩니다.

• 헤더 메타데이터 카드: 테스트 이름, 미리보기 방법, 변형, 스위트, 상태 배지를 표시합니다.
• 오류 분류: 복사 가능한 스택 트레이스를 사용하여 Reference Image Missing, Image Size Mismatch 또는 Pixel Mismatch에 명확하게 플래그를 지정합니다.
• 동적 시각적 차이: 중첩된 요소가 사라지는 것을 방지하기 위해 미묘한 수정사항은 낮은 강도로, 주요 변경사항은 고대비 강조로 표시합니다.

기존 독립형 플러그인에서 마이그레이션

기존 독립형 스크린샷 플러그인에서 AGP 테스트 모음으로 이전하려면 Gradle 구성과 작업 명령어를 업데이트하세요.

빌드 구성 DSL 비교

기존 독립형 플러그인 (지원 중단됨)

// In build.gradle.kts
plugins {
    alias(libs.plugins.screenshot)
}

dependencies {
    screenshotTestImplementation(libs.androidx.compose.ui.tooling)
    screenshotTestImplementation("com.android.tools.screenshot:screenshot-validation-api:0.0.1-alpha16")
}

AGP 테스트 모음 (권장)

// In build.gradle.kts
android {
    testOptions {
        screenshotTests.create("screenshotTest") {
            engineVersion = "0.0.1-alpha16"
            targetVariants.add("demoDebug")

            dependencies {
                implementation(libs.androidx.compose.ui.tooling)
                implementation("com.android.tools.screenshot:screenshot-validation-api:0.0.1-alpha16")
            }
        }
    }
}

작업 및 경로 매핑