tt/VibeCoding
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

skill: add Android skills

Browse Source
This commit is contained in:
tongtongstudio
2026-07-14 10:34:54 +08:00
parent e260c02629
commit ab82fb7cf0
182 changed files with 62992 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

287
.agents/skills/r8-analyzer/references/CONFIGURATION-ANALYZER.md Normal file
View File

File diff suppressed because one or more lines are too long

44
.agents/skills/r8-analyzer/references/CONFIGURATION.md Normal file
View File

@@ -0,0 +1,44 @@
To achieve maximum utilization of R8, the codebase must be configured correctly
depending on the build script language (Kotlin DSL versus Groovy DSL).
## 1. App Modules (`com.android.application`)
The app's `build.gradle` or `build.gradle.kts` file must enable minification
and resource shrinking within the `release` build type or the apps custom build
type for release and performance testing. It MUST use the optimized default file
(`proguard-android-optimize.txt`).
**Kotlin DSL (`build.gradle.kts`):**
buildTypes {
getByName("release") {
isMinifyEnabled = true
isShrinkResources = true
proguardFiles(
getDefaultProguardFile("proguard-android-optimize.txt"),
"proguard-rules.pro"
)
}
}
**Groovy DSL (`build.gradle`):**
buildTypes {
release {
minifyEnabled = true
shrinkResources = true
proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
}
}
## 2. `gradle.properties` Flags
**Full Mode:** R8 Full Mode enables the entire optimizations
- **AGP 8.0+** : Enabled by default. Ensure `android.enableR8.fullMode=false` is **NOT** present.
- **Pre-AGP 8.0** : Explicitly enable with `android.enableR8.fullMode=true`.
**Optimized Resource Shrinking:** If the AGP version of the project is less than
9.0 and more than 8.6, explicitly enable the new resource shrinker:
android.r8.optimizedResourceShrinking=true

83
.agents/skills/r8-analyzer/references/KEEP-RULES-IMPACT-HIERARCHY.md Normal file
View File

@@ -0,0 +1,83 @@
Keep rules prevent optimization of R8, these rules are listed in the order of
the scope of what it retains in the codebase.
## 1. Package-Wide Wildcards
The following types of keep rules prevents all the optimization of R8 in a
package, these must be avoided at any costs and must be refined to target a
specific class or classes.
-keep class com.example.package.** { *; } - Prevents optimization of all the classess including members in the package and subpackages
-keep class com.example.package.* { *; } - Prevents optimization of all the classes including members in the package
-keep class **.package.** { *; } - Prevents optimization of all the classess including members in all the package containing name - package.
Depending on the package level the number of classes gets affected changes, so
if the package level is higher, more classes are affected. Suggest to refine
the keep rule
## 2. Inversion operator
Avoid using the inversion operator ! in keep rules because it will
unintentionally prevent optimization in every class in your application. So if
you have any keep rule with !operator, make sure you remove that with a narrow
and specific keep rule
-keep class !com.example.MyClass{*;}
This keeps the entire app
other than this class. Optimization are disabled for the entire class other
than this class.
## 3. Keep Rules for both class and members
Keep rules with -keep option and wildcard(`*`) inside braces forces R8 to retain
specific classes and their members exactly as defined. These type of keep rules
prevent any optimization in the entire class and keeps the entire class
-keep class com.example.MyClass { *; }
## 4. Keepclassmembers
Keep rules with -keepclassmembers and wildcard(`*`) inside braces option Forces
R8 to retain the members that are defined.
-keepclassmembers class com.example.MyClass { *; }
## 5. Modifiers with Keep Specification
-Keeps the class and **all** members, but uses modifiers to allow specific
optimizations (like obfuscation). Retains significant code (members) but allows
some flexibility.
-keep,allowobfuscation class com.example.MyClass { *; }
-keep,allowshrinking class com.example.MyClass { *; }
### 6. Modifiers with specific method but no modifier
Keeps the class and modifier but no optimizations are enabled
-keep class com.example.MyClass { void myMethod(); }
## 7. Class-Name Only Preservation
Keeps only the class name. R8 will remove all methods and fields if they are not
used.
-keep class com.example.MyClass
## 8. Modifiers without Member Specification
Keeps the class entry point using modifiers, but implies no specific member
retention logic in the rule itself
-keep,allowobfuscation class com.example.MyClass
-keep,allowshrinking class com.example.MyClass
-keep,allowaccessmodification class com.example.MyClass
## 9. Conditional Keep Rules
Only triggers if specific conditions are met (e.g., if class members exist).
These are the most narrow and optimization-friendly rules.
-keepclassmembers class com.example.MyClass { <fields>; }
-keepclasseswithmembers class * { native <methods>; }

222
.agents/skills/r8-analyzer/references/REDUNDANT-RULES.md Normal file
View File

@@ -0,0 +1,222 @@
This document outlines common "bad" or redundant keep rules for standard Android
development and popular libraries. Modern toolchains and libraries include their
own consumer keep rules embedded in their AAR/JAR files, making many manual
configurations unnecessary or even harmful to code optimization.
*** ** * ** ***
## Case: Global Keep Rules
**Common Mistakes:**
`proguard
-dontshrink
-dontobfuscate
-dontoptimize`
**The Fix:** These keep rules completely disable the core optimizations of R8
for the entire codebase. They must be removed from the codebase.
*** ** * ** ***
## Case: Android Components
Keep rules required for Android components like Activity, Fragment, ViewModel,
Views, Services or Broadcast receivers are redundant. AAPT2 and R8 contain the
logic to automatically keep components declared in the `AndroidManifest.xml` or
referenced in XML layout files.
**Common Mistakes:**
`proguard
-keep public class * extends android.app.Activity
-keep public class * extends android.app.Service
-keep public class * extends android.view.View
-keepclassmembers class * extends android.app.Fragment { public void *(android.view.View); }`
**The Fix:** Delete these manual rules. AAPT2 handles this automatically.
*** ** * ** ***
## Case: Official Android and Kotlin Libraries
Keep rules targeting official library packages like AndroidX, Kotlin, and
Kotlinx are redundant as they are bundled within the libraries themselves.
Manual rules are often broader than what is strictly needed.
**Common Mistakes:**
`proguard
-keep class androidx.** { *; }
-keep class kotlinx.** { *; }
-keep class kotlin.** { *; }`
**The Fix:** Delete these manual rules. Rely on the consumer keep rules packaged
within these dependencies.
*** ** * ** ***
## Case: Gson
### Overly Broad Data Model Rules
The most common mistake is keeping entire packages of data models (POJOs/DTOs),
keeping data models at all for deserialization is unnecessary.
-keep class com.example.app.models.** { *; }
-keep class com.example.app.package.models.* { *; }
### Redundant Interface \& Adapter Rules
These rules added for TypeAdapter are unnecessary and are already covered by
the library, and prevent R8 from effectively shrinking and optimizing custom
adapters. R8 can determine if the adapter implementation are used. Keeping them
globally prevents the removal of unused adapter implementations.
-keep class * extends com.google.gson.TypeAdapter
-keep class * implements com.google.gson.TypeAdapterFactory
-keep class * implements com.google.gson.JsonSerializer
-keep class * implements com.google.gson.JsonDeserializer
### Unnecessary TypeToken Rules
There is no need to handle generic type erasure, Gson's own rules handle the
necessary `TypeToken` preservation.
-keep class com.google.gson.reflect.TypeToken { *; }
-keep class * extends com.google.gson.reflect.TypeToken
-keep,allowobfuscation,allowshrinking class com.google.gson.reflect.TypeToken
### Internal and Example Packages
Keeping internal library logic prevents the compiler from stripping away dead
code within the library.
-keep class com.google.gson.internal.** { *; }
-keep class com.google.gson.internal.reflect.** { *; }
-keep class com.google.gson.internal.UnsafeAllocator { *; }
-keep class com.google.gson.stream.** { *; }
- **Keeps Unused Code:** Prevents R8 from removing models that are never actually used in the code.
- **Prevents Method Stripping:** Keeps all getters, setters, `toString()`, `equals()`, and `hashCode()` methods, even if they are never called.
- **Blocks Obfuscation:** Prevents the class names from being obfuscated, which is unnecessary for Gson if you use `@SerializedName`.
**The Fix:**
1. Use `@SerializedName` on every field in your data classes uses so that the field is retained after R8 optimization
2. Modern Gson (**v2.11.0+** ) bundles its own rules ([View Gson's embedded
ProGuard
rules](https://github.com/google/gson/blob/main/gson/src/main/resources/META-INF/proguard/gson.pro)). The bundled keep rules retains the `@SerializedName` annotated fields. If you are on an older version, move towards Gson version 2.11 because it has the necessary keep rules and delete the keep rules that target the classes used for gson serialization and deserialization
*** ** * ** ***
## Case: Retrofit
Retrofit has shipped with its own consumer keep rules from 2.9.0 and higher, so
any keep rules for the library or classes depending on Retrofit is detrimental
to the optimization process.
### Blanket Library Preservation
This is the most harmful Retrofit rule as it disables any shrinking for the
entire library.
-keep class retrofit2.** { *; }
-keep class retrofit2.api.** { *; }
-keep class com.package.example.retrofit.api.** { *; }
### Manual Annotation Keeps
Retrofit's consumer rules automatically keep the interfaces annotated with
`@GET`, `@POST`, `@DELETE`, `@PUT`, `@HEAD`, `@OPTIONS`, `@PATCH`, making these
manual rules obsolete.
`-keepclasseswithmembers class * { @retrofit2.http.* <methods>; }`
### Redundant Network Response and Adapter Rules
Network responses and third-party adapter wrappers (like RxJava) are often
overly preserved by developers out of caution.
-keep,allowobfuscation,allowshrinking class retrofit2.Response
-keep class retrofit2.adapter.rxjava2.Result { *; }
Fix: Verify you are using Retrofit 2.9.0 and higher. Retrofit from 2.9.0 bundles
rules that detect its own HTTP annotations (@GET, @POST) ([View Retrofit's
embedded ProGuard
rules](https://github.com/square/retrofit/blob/master/retrofit/src/main/resources/META-INF/proguard/retrofit2.pro)).
It will automatically keep the method signatures it needs to work.
*** ** * ** ***
## Case: Kotlin Coroutines
Kotlin Coroutines comes heavily optimized out of the box with embedded R8 rules
(`kotlinx-coroutines-core` includes its own rules).
### Blanket Coroutine Library Rules
Keeping everything under `kotlinx.coroutines` is extremely detrimental to app
size, as coroutines contain a vast amount of internal APIs that aren't used.
`-keepclassmembers class kotlinx.coroutines.** { *; }`
### Redundant Internal Continuations
These low-level coroutine elements are preserved safely by the library's own
consumer rules. Manually adding these prevents R8 from performing internal
optimizations (such as removing unused continuations or inlining).
-keepclassmembers class kotlin.coroutines.SafeContinuation { *; }
-keep,allowobfuscation,allowshrinking class kotlin.coroutines.Continuation
### Dispatcher and Exception Handler Rules
Sometimes developers notice crashes related to Missing Classes on old Android
versions and add these rules, but if you are using an up-to-date version of
Coroutines, these are handled automatically or are not an issue.
-keepnames class kotlinx.coroutines.internal.MainDispatcherFactory {}
-keepnames class kotlinx.coroutines.CoroutineExceptionHandler {}
-keepnames class kotlinx.coroutines.android.AndroidExceptionPreHandler {}
-keepnames class kotlinx.coroutines.android.AndroidDispatcherFactory {}
**Fix** Remove any broad `kotlinx` keep rules. Coroutines (**v1.7.0+** ) bundle
the necessary keep rules ([View Coroutines' embedded ProGuard
rules](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/resources/META-INF/proguard/coroutines.pro)).
*** ** * ** ***
## Case: Parcelable
**Common Mistakes:** Legacy projects often contain `-keep class * implements
android.os.Parcelable { public static final android.os.Parcelable$Creator *; }`.
**The Fix:**
1. Add the `kotlin-parcelize` plugin.
2. **Use `@Parcelize`:** Replace manual `writeToParcel` logic with the `@Parcelize` annotation.
3. **Delete All Parcelable Rules:** The plugin automatically generates the required rules.
4. The default proguard file `proguard-android-optimize.txt` contains the keep rules for keeping all the parcelable classes
5. **Ideal Rule:** **None.** Delete all manual Parcelable keeps.
*** ** * ** ***
## Case: Room Database
**Common Mistakes:** Keeping DAO interfaces or the generated `_Impl` classes
manually.
-keep class * extends androidx.room.RoomDatabase
-keep class *_*Impl { *; }
**The Fix:** Room generates its own ProGuard rules for the code it creates.
Manual rules are redundant and prevent R8 from optimizing the database access
layers.
- **Ideal Rule:** **None.** Delete all manual Room or DAO keeps.
*** ** * ** ***
## Summary
If you have updated your libraries to the versions mentioned, your
`proguard-rules.pro` must not contain any keep rules for the libraries
mentioned here.

139
.agents/skills/r8-analyzer/references/REFLECTION-GUIDE.md Normal file
View File

@@ -0,0 +1,139 @@
A categorized summary of the keep rule examples, including the code patterns to
look for (imports/usage) and the corresponding suggested rules.
### 1. Reflection: Classes Loaded by Name
**Scenario:** A library or app loads a class dynamically using a string name
- **Look for:**
`Class.forName("...")`,
`getDeclaredConstructor().newInstance()`, or interfaces used for dynamic loading.
- **Example Code:**
`kotlin
val taskClass = Class.forName(className)
val task = taskClass.getDeclaredConstructor().newInstance() as StartupTask`
- **Suggested Keep Rule:**
\`\`\`proguard
-keep class \* implements com.example.library.StartupTask {
(); } \`\`\`
### 2. Reflection: Classes Passed using `::class.java`
**Scenario:** An app passes a class reference directly to a library function.
- **Look for:** `::class.java` (Kotlin) or `.class` (Java) passed as an argument.
- **Example Code:**
`kotlin
fun <T> register(clazz: Class<T>) { }
// Usage:
register(MyService::class.java)`
- **Suggested Keep Rule:**
\`\`\`proguard
# Keep the class itself (R8 usually handles this, but explicit rules ensure stability)
-keep class com.example.app.MyService {
(); } \`\`\`
### 3. Annotation-Based Reflection (Methods/Classes)
**Scenario:** Using custom annotations to mark methods or classes for reflective
execution.
**Look for:** Custom `@interface` definitions and `getDeclaredMethods()`
filtered by annotation.
**Example Code:**
`kotlin
annotation class ReflectiveExecutor
// Logic: find methods annotated with @ReflectiveExecutor and invoke them`
- **Suggested Keep Rule:** \`\`\`proguard # Keep the annotation itself -keep @interface com.example.library.ReflectiveExecutor
# Keep members of any class annotated with this specific annotation
-keepclassmembers class \* {
@com.example.library.ReflectiveExecutor \*;
}
\`\`\`
### 4. Optional Dependencies (Soft Dependencies)
**Scenario:** A core library checks if an optional module is present in the
classpath.
- **Look for:** `try-catch` blocks around `Class.forName()` used to toggle features.
- **Example Code:** \`\`\`kotlin private const val VIDEO_TRACKER_CLASS = "com.example.analytics.video.VideoEventTracker"
try {
Class.forName(VIDEO_TRACKER_CLASS).getDeclaredConstructor().newInstance()
} catch (e: ClassNotFoundException) { /\* skip feature \*/ }
\`\`\`
- **Suggested Keep Rule:** `proguard
# Preserve the optional class so the check doesn't fail due to shrinking
-keep class com.example.analytics.video.VideoEventTracker {
<init>();
}`
### 5. Accessing Private Members
**Scenario:** Using reflection to access internal fields or methods not exposed
with public APIs.
- **Look for:** `getDeclaredField("...")` or `getDeclaredMethod("...")` followed by `isAccessible = true`.
- **Example Code:**
`kotlin
val secretField = instance::class.java.getDeclaredField("secretMessage")
secretField.isAccessible = true`
- **Suggested Keep Rule:**
\`\`\`proguard
# Specifically keep the private field/method by name and type
-keepclassmembers class com.example.LibraryClass {
private java.lang.String secretMessage;
}
\`\`\`
### 6. Parcelable (Manual Implementation)
**Scenario:** Implementing `Parcelable` without using the `@Parcelize`
annotation.
- **Look for:** `implements Parcelable` and a static `CREATOR` field.
- **Example Code:**
`kotlin
class MyData : Parcelable {
// Manual implementation with CREATOR field
}`
- **Suggested Keep Rule:**
*(Note: If using `import kotlinx.parcelize.Parcelize`, R8/ProGuard rules are
generated automatically. If manual, use the following:)*
`proguard
-keepclassmembers class * implements android.os.Parcelable {
static android.os.Parcelable$Creator CREATOR;
}`
### 7. Enums and Obfuscation
**Scenario:** App uses `Enum.valueOf("STRING_NAME")` indirectly (e.g.,using JSON
deserialization) and the enum names get obfuscated.
- **Look for:** Unnecessary generic Enum keep rules in ProGuard files.
- **Example Code:**
\`\`\`proguard
# Unnecessary rule
-keepclassmembers enum \* { \*; }
\`\`\`
- **Suggested Keep Rule:**
\*(Note: The default `proguard-android-optimize.txt` already contains the optimal
rules for Enums (keeping `values()` and `valueOf(String)`). Any additional
manual rules for Enums are redundant.) # No manual rule needed. Use default
proguard-android-optimize.txt.

51
.agents/skills/r8-analyzer/references/REPORT_FORMAT.md Normal file
View File

@@ -0,0 +1,51 @@
## 1. Configuration
*(Optional section for the report, omit if no relevant findings are present.)*
- **AGP Version**: \[Current\] -\> Upgrade to 9.0.
- **Full Mode** : Not enabled. Remove `android.enableR8.fullMode=false` from `gradle.properties`.
## 2. Global disable rules
*(Optional section for the report, omit if no relevant findings are present.)*
- \[Rule\]: Disables R8 globally. **Action**: Remove.
If there is -dontobfuscate, -dontoptimize or -dontshrink in the codebase,
mention in this section
## 3. Optimization summary
- **Optimization score**: \[X\]% code is available for R8 optimizations (e.g., inlining, merging). \[100-X\]% of codebase can't be optimized by R8.
- **Shrinking score**: \[X\]% of code will be optimized by R8 by removing unused classes, fields and methods. \[100-X\]% of codebase contains redundant classes, fields and methods that can't be removed by R8.
- **Obfuscation score**: \[X\]% of the codebase is available for R8 to obfuscate.
Increasing these scores increases the codebase available to R8 for
optimizations.
## 4. Keep rules evaluation
### \[Rule text\]
- **Keeps**: \[X\] items or \[X\] % of the codebase from optimization. Classes: \[X\], Fields: \[X\], Methods: \[X\] are prevented from optimization due to this keep rule
- **Kept items**: \[Class1\], \[Class2\]
- **Action** : **Remove** (Library bundles rules) OR **Refine** (Too broad, use \[Surgical Rule\]).
## 5. Subsumed keep rules
*(Optional section for the report, omit if no relevant findings are present.)*
### \[Redundant rules\]
- **Subsumed By**: \[Broader Rule\]
- **Action** : **Remove**.
## 6. Historical analysis summary
*(Only include this section if a previous report existed. Summarize the changes
in optimization scores here to track progress. For example:)* The previous app
had scores: Optimization (XX%), Obfuscation (XX%), and Shrinking (XX%). The
current app has scores: Optimization (YY%), Obfuscation (YY%), and Shrinking
(YY%).
**Change**: Optimization improved by ZZ%, Obfuscation improved by ZZ%, and
Shrinking improved by ZZ%.

198
.agents/skills/r8-analyzer/references/android/topic/performance/app-optimization/enable-app-optimization.md Normal file
View File

@@ -0,0 +1,198 @@
For the best user experience, you should optimize your app to make it as small
and fast as possible. Our app optimizer, called R8, streamlines your app by
removing unused code and resources, rewriting code to optimize runtime
performance, and more. To your users, this means:
- Faster startup time
- Reduced memory usage
- Improved rendering and runtime performance
- Fewer [ANRs](https://developer.android.com/topic/performance/anrs/keep-your-app-responsive)
> [!IMPORTANT]
> **Important:** You should always enable optimization for your app's release build; however, you probably don't want to enable it for tests or libraries. For more information about using R8 with tests, see [Test and troubleshoot the
> optimization](https://developer.android.com/topic/performance/app-optimization/test-and-troubleshoot-the-optimization). For more information about enabling R8 from libraries, see [Optimization for library authors](https://developer.android.com/topic/performance/app-optimization/library-optimization).
> [!IMPORTANT]
> **Important:** We released an agent skill that you can use to improve your app performance with R8. Try out the skill from the [Android skills repository](https://github.com/android/skills).
## R8 optimization overview
R8 uses a multi-phase process to optimize your app for size and speed. Key
operations include the following:
- **Code shrinking (also known as tree shaking)** : R8 identifies and removes
unreachable code from your application and its library dependencies. By
analyzing the entry points of your app (such as `Activities` or `Services`
defined in the manifest), R8 builds a graph of referenced code and removes
anything that remains unreferenced.
- **Logical optimizations**: R8 rewrites your code to improve execution
efficiency and reduce overhead. Key techniques include:
- **Method inlining**: R8 replaces a method call site with the actual body
of the called method. This eliminates the overhead of a function call
and lets R8 conduct further optimizations.
- **Class merging**: R8 combines sets of classes and interfaces into a
single class. This reduces the number of classes in the app, lowering
memory pressure and improving startup speed.
- **Obfuscation (also known as minification)** : To reduce the size of the DEX
file, R8 shortens the names of classes, fields, and methods (for example,
`com.example.MyActivity` could become `a.b.a`).
Since 8.12.0 version of Android Gradle Plugin (AGP), R8 also optimizes resources
as part of its optimization phases. For more information, see [Optimized
resource shrinking](https://developer.android.com/topic/performance/app-optimization/enable-app-optimization#optimize-resource-shrinking).
## Enable optimization
To enable app optimization, set `isMinifyEnabled = true` (for code optimization)
and `isShrinkResources = true` (for resource optimization) in your [release
build's](https://developer.android.com/studio/publish/preparing#turn-off-debugging) app-level build script as shown in the following code. We recommend
that you always enable both settings. We also recommend enabling app
optimization only in the final version of your app that you test before
publishing---usually your release build---because the optimizations increase the
build time of your project and can make debugging harder due to the way it
modifies code.
### Kotlin
```kotlin
android {
buildTypes {
release {
// Enables code-related app optimization.
isMinifyEnabled = true
// Enables resource shrinking.
isShrinkResources = true
proguardFiles(
// Default file with automatically generated optimization rules.
getDefaultProguardFile("proguard-android-optimize.txt"),
...
)
...
}
}
...
}
```
### Groovy
```groovy
android {
buildTypes {
release {
// Enables code-related app optimization.
minifyEnabled = true
// Enables resource shrinking.
shrinkResources = true
// Default file with automatically generated optimization rules.
proguardFiles getDefaultProguardFile('proguard-android-optimize.txt')
...
}
}
}
```
## Improve R8 optimization
The performance benefits of R8 are directly correlated to how much of your
codebase R8 is able to optimize. To get the maximum benefits out of R8, follow
best practices:
- Enable R8 in [full mode](https://developer.android.com/topic/performance/app-optimization/full-mode)
- Enable [obfuscation, optimization, and shrinking](https://developer.android.com/topic/performance/app-optimization/adopt-optimizations-incrementally)
- Enable resource shrinking and [optimized resource shrinking](https://developer.android.com/topic/performance/app-optimization/enable-app-optimization#optimize-resource-shrinking)
- [Refine keep rules](https://developer.android.com/topic/performance/app-optimization/keep-rules-best-practices) to allow maximum optimization of classes, fields and methods.
To help you refine keep rules, use the [R8 Configuration Analyzer](https://developer.android.com/topic/performance/app-optimization/r8-configuration-analyzer).
The R8 Configuration Analyzer lets you do the following:
- Track and improve the overall R8 configuration quality by monitoring the metrics provided by the R8 Configuration Analyzer report.
- Find the broadest keep rules - those which prevent the most optimization
- and understand what optimization they prevent to refine them.
The R8 Configuration Analyzer is available in AGP version 9.3.0-alpha05 or from
R8 version 9.3.7-dev. For more information, see [Analyze R8 configuration](https://developer.android.com/topic/performance/app-optimization/r8-configuration-analyzer).
## Optimize resource shrinking for even smaller apps
The 8.12.0 version of Android Gradle Plugin (AGP) introduces optimized resource
shrinking, which aims to integrate resource and code optimization to create even
smaller and faster apps.
Before optimized resource shrinking, Android Asset Packaging Tool (AAPT2)
generated keep rules that effectively treating resource shrinking separately
from code, often retaining inaccessible code or resources that referenced each
other.
With optimized resource shrinking, resources are considered like a part of
program code, forming the reference graph. When a collection of code or
resources is not referenced, it is not protected by a keep rule, and can be
removed.
### Enable optimized resource shrinking
To enable the new optimized resource shrinking pipeline for AGP 8.12 or 8.13,
add the following to your project's `gradle.properties` file:
android.r8.optimizedResourceShrinking=true
If you are using AGP 9.0.0 or a newer version, you don't need to set
`android.r8.optimizedResourceShrinking=true`. Optimized resource shrinking is
automatically applied when `isShrinkResources = true` is enabled in your build
configuration.
## Verify and configure R8 optimization settings
To enable R8 to use its [full optimization capabilities](https://developer.android.com/topic/performance/app-optimization/full-mode), remove the
following line from your project's `gradle.properties` file, if it exists:
android.enableR8.fullMode=false # Remove this line from your codebase.
Note that enabling app optimization makes stack traces difficult to understand,
especially if R8 renames class or method names. To get stack traces that
correctly correspond to your source code, see [Recover the original stack
trace](https://developer.android.com/topic/performance/app-optimization/test-and-troubleshoot-the-optimization#recover-original-stack-trace).
If R8 is enabled, you should also [create Startup Profiles](https://developer.android.com/topic/performance/baselineprofiles/dex-layout-optimizations) for even better
startup performance.
If you enable app optimization and it causes errors, here are some strategies to
fix them:
- [Add keep rules](https://developer.android.com/topic/performance/app-optimization/add-keep-rules) to keep some code untouched.
- [Adopt optimizations incrementally](https://developer.android.com/topic/performance/app-optimization/adopt-optimizations-incrementally).
- Update your code to [use libraries that are better suited for
optimization](https://developer.android.com/topic/performance/app-optimization/choose-libraries-wisely).
> [!CAUTION]
> **Caution:** Tools that replace or modify R8's output can negatively impact runtime performance. R8 is careful about including and testing many optimizations at the code level, in [DEX layout](https://developer.android.com/topic/performance/baselineprofiles/dex-layout-optimizations), and in correctly producing Baseline Profiles - other tools producing or modifying DEX files can break these optimizations, or otherwise regress performance.
If you are interested in optimizing your build speed, see [Configure how R8
runs](https://developer.android.com/build/r8-execution-profiles) for information on how to configure R8 based on your environment.
## AGP and R8 version behavior changes
The following table outlines the key features introduced in various versions of
the Android Gradle Plugin (AGP) and the R8 compiler.
| AGP version | Features introduced |
|---|---|
| 9.1 | **Classes repackaged by default:** R8 repackages classes (moving them to the unnamed package, at the top level) to compact DEX further, eliminating the need to specify `-repackageclasses` option. For information about how this works and how to opt out, see [global options](https://developer.android.com/topic/performance/app-optimization/global-options#global-options). |
| 9.0 | **Optimized resource shrinking:** Enabled by default (controlled using `android.r8.optimizedResourceShrinking`). [Optimized resource shrinking](https://developer.android.com/topic/performance/app-optimization/enable-app-optimization#optimize-resource-shrinking) helps integrate resource shrinking with the code optimization pipeline, leading to smaller, faster apps. By optimizing both code and resource references simultaneously, it identifies and removes resources referenced exclusively from unused code. This is a significant improvement over the previous separate optimization processes. This is especially useful for apps that share substantial resources and code across different form factor verticals, with measured improvements of over 50% in app size. The resulting size reduction leads to smaller downloads, faster installations, and a better user experience with faster startup, improved rendering, and fewer ANRs. **Library rule filtering:** Support for global options (for example, `-dontobfuscate`) in library consumer rules has been dropped, and apps will filter them out. For more information, see [Add global options](https://developer.android.com/topic/performance/app-optimization/global-options). **Kotlin null checks:** Optimized by default (controlled using `-processkotlinnullchecks`). This version also introduced significant improvements in build speed. For more information, see [Global options for additional optimization](https://developer.android.com/topic/performance/app-optimization/global-options#global-options). **Optimize specific packages:** You can use `packageScope` to optimize specific packages. This is in experimental support. For more information, see [Optimize specified packages with `packageScope`](https://developer.android.com/topic/performance/app-optimization/optimize-specified-packages). **Optimized by default:** Support for `getDefaultProguardFile("proguard-android.txt")` has been dropped, because it includes `-dontoptimize`, which should be avoided. Instead, use `"proguard-android-optimize.txt"`. If you need to globally disable optimization in your app, [add the flag manually to a proguard file](https://developer.android.com/topic/performance/app-optimization/global-options#global-options-2). |
| 8.12 | **Optimized resource shrinking:** Initial support added (controlled using `android.r8.optimizedResourceShrinking`). [Optimized resource shrinking](https://developer.android.com/topic/performance/app-optimization/enable-app-optimization#optimize-resource-shrinking) helps integrate resource shrinking with the code optimization pipeline. You must manually enable it in this version of AGP. **Logcat retracing:** Support for automatic retracing in the Android Studio [Logcat window](https://developer.android.com/studio/debug/logcat). |
| 8.6 | **Improved retracing:** Includes filename and line number retracing by default for all `minSdk` levels (previously required `minSdk` 26+ in version 8.2). Updating R8 helps ensure that stack traces from obfuscated builds are readily and clearly readable. This version improves how line numbers and source files are mapped, making it easier for tools like the Android Studio Logcat to automatically retrace crashes to the original source code. |
| 8.0 | **Full mode by default:** [R8 full mode](https://developer.android.com/topic/performance/app-optimization/full-mode) provides significantly more powerful optimization. It is enabled by default. You can opt out using `android.enableR8.fullMode=false`. |
| 7.0 | **Full mode available:** Introduced as an opt-in feature using `android.enableR8.fullMode=true`. Full mode applies more powerful optimizations by making stricter assumptions about how your code uses reflection and other dynamic features. While it reduces app size and improves performance, it might require additional keep rules to prevent necessary code from being stripped. |

312
.agents/skills/r8-analyzer/references/android/training/testing/other-components/ui-automator.md Normal file
View File

@@ -0,0 +1,312 @@
The UI Automator testing framework provides a set of APIs to build UI tests that
interact with user apps and system apps.
> [!NOTE]
> **Note:** This documentation covers the modern approach to writing UI Automator tests, introduced with [UI Automator 2.4](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.0). This approach makes your tests more concise, readable, and robust. The API is under development, and we strongly recommend using it for any new development with UI Automator. The [legacy API guidance](https://developer.android.com/training/testing/other-components/ui-automator-legacy) is also available.
## Introduction to modern UI Automator testing
UI Automator 2.4 introduces a streamlined, Kotlin-friendly Domain Specific
Language (DSL) that simplifies writing UI tests for Android. This new API
surface focuses on predicate-based element finding and explicit control over app
states. Use it to create more maintainable and reliable automated tests.
UI Automator lets you test an app from outside of the app's process. This
lets you test release versions with minification applied. UI Automator also
helps when writing macrobenchmark tests.
Key features of the modern approach include:
- A dedicated `uiAutomator` test scope for cleaner and more expressive test code.
- Methods like `onElement`, `onElements`, and `onElementOrNull` for finding UI elements with clear predicates.
- Built-in waiting mechanism for conditional elements `onElement*(timeoutMs:
Long = 10000)`
- Explicit app state management such as `waitForStable` and `waitForAppToBeVisible`.
- Direct interaction with accessibility window nodes for multi-window testing scenarios.
- Built-in screenshot capabilities and a `ResultsReporter` for visual testing and debugging.
## Set up your project
To begin using the modern UI Automator APIs, update your project's
`build.gradle.kts` file to include the [latest dependency](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.0):
### Kotlin
dependencies {
...
androidTestImplementation("androidx.test.uiautomator:uiautomator:2.4.0-alpha05")
}
### Groovy
dependencies {
...
androidTestImplementation "androidx.test.uiautomator:uiautomator:2.4.0-alpha05"
}
## Core API concepts
The following sections describe core concepts of the modern UI Automator API.
### The uiAutomator test scope
Access all new UI Automator APIs within the **`uiAutomator { ... }`**
block. This function creates a `UiAutomatorTestScope` that provides a concise
and type-safe environment for your test operations.
uiAutomator {
// All your UI Automator actions go here
startApp("com.example.targetapp")
onElement { textAsString() == "Hello, World!" }.click()
}
### Find UI elements
Use UI Automator APIs with predicates to locate UI elements. These predicates
let you define conditions for properties such as text, selected or focused
state, and content description.
- `onElement { predicate }`: Returns the first UI element that matches the
predicate within a default timeout. The function throws an exception if it
doesn't locate a matching element.
// Find a button with the text "Submit" and click it
onElement { textAsString() == "Submit" }.click()
// Find a UI element by its resource ID
onElement { viewIdResourceName == "my_button_id" }.click()
// Allow a permission request
watchFor(PermissionDialog) {
clickAllow()
}
- `onElementOrNull { predicate }`: Similar to `onElement`, but returns
`null` if the function finds no matching element within the timeout. It
doesn't throw an exception. Use this method for optional elements.
val optionalButton = onElementOrNull { textAsString() == "Skip" }
optionalButton?.click() // Click only if the button exists
- `onElements { predicate }`: Waits until at least one UI element matches
the given predicate, then returns a list of all matching UI elements.
// Get all items in a list Ui element
val listItems = onElements { className == "android.widget.TextView" && isClickable }
listItems.forEach { it.click() }
Here are some tips for using `onElement` calls:
- Chain `onElement` calls for nested elements: You can chain `onElement`
calls to find elements within other elements, following a parent-child
hierarchy.
// Find a parent Ui element with ID "first", then its child with ID "second",
// then its grandchild with ID "third", and click it.
onElement { viewIdResourceName == "first" }
.onElement { viewIdResourceName == "second" }
.onElement { viewIdResourceName == "third" }
.click()
- Specify a timeout for `onElement*` functions by passing a value representing
milliseconds.
// Find a Ui element with a zero timeout (instant check)
onElement(0) { viewIdResourceName == "something" }.click()
// Find a Ui element with a custom timeout of 10 seconds
onElement(10_000) { textAsString() == "Long loading text" }.click()
### Interact with UI elements
Interact with UI elements by simulating clicks or setting text in editable
fields.
// Click a Ui element
onElement { textAsString() == "Tap Me" }.click()
// Set text in an editable field
onElement { className == "android.widget.EditText" }.setText("My input text")
// Perform a long click
onElement { contentDescription == "Context Menu" }.longClick()
## Handle app states and watchers
Manage the lifecycle of your app and handle unexpected UI elements that might
appear during your tests.
### App lifecycle management
The APIs provide ways to control the state of the app under test:
// Start a specific app by package name. Used for benchmarking and other
// self-instrumenting tests.
startApp("com.example.targetapp")
// Start a specific activity within the target app
startActivity(SomeActivity::class.java)
// Start an intent
startIntent(myIntent)
// Clear the app's data (resets it to a fresh state)
clearAppData("com.example.targetapp")
### Handle unexpected UI
The `watchFor` API lets you define handlers for unexpected UI elements,
such as permission dialogs, that might appear during your test flow. This
uses the internal watcher mechanism but offers more flexibility.
import androidx.test.uiautomator.PermissionDialog
@Test
fun myTestWithPermissionHandling() = uiAutomator {
startActivity(MainActivity::class.java)
// Register a watcher to click "Allow" if a permission dialog appears
watchFor(PermissionDialog) { clickAllow() }
// Your test steps that might trigger a permission dialog
onElement { textAsString() == "Request Permissions" }.click()
// Example: You can register a different watcher later if needed
clearAppData("com.example.targetapp")
// Now deny permissions
startApp("com.example.targetapp")
watchFor(PermissionDialog) { clickDeny() }
onElement { textAsString() == "Request Permissions" }.click()
}
`PermissionDialog` is an example of a `ScopedWatcher<T>`, where `T` is the
object passed as a scope to the block in `watchFor`. You can create custom
watchers based on this pattern.
### Wait for app visibility and stability
Sometimes tests need to wait for elements to become visible or stable.
UI Automator offers several APIs to help with this.
The `waitForAppToBeVisible("com.example.targetapp")` waits for a UI element with
the given package name to appear on the screen within a customizable timeout.
// Wait for the app to be visible after launching it
startApp("com.example.targetapp")
waitForAppToBeVisible("com.example.targetapp")
Use the `waitForStable()` API to verify that the app's UI is considered stable
before interacting with it.
// Wait for the entire active window to become stable
activeWindow().waitForStable()
// Wait for a specific Ui element to become stable (e.g., after a loading animation)
onElement { viewIdResourceName == "my_loading_indicator" }.waitForStable()
> [!NOTE]
> **Note:** In most cases, `waitForStable()` isn't strictly necessary when using `onElement { ... }` because `onElement` already includes a timeout. Use `waitForStable()` primarily in combination with `onElements { ... }` to verify that all UI elements are visible, when you know that the UI is in an unstable state, or for specific screenshot testing scenarios where you need the UI to completely settle before capturing. `waitForStable()` works by waiting until no changes are detected in the accessibility tree for a set period. Note that this UI stability check doesn't guarantee that the app is fully idle, as background tasks might still be running.
## Use UI Automator for Macrobenchmarks and Baseline Profiles
Use UI Automator for performance testing with [Jetpack Macrobenchmark](https://developer.android.com/topic/performance/benchmarking/macrobenchmark-overview)
and for generating [Baseline Profiles](https://developer.android.com/topic/performance/baselineprofiles/overview), as it provides a reliable way to
interact with your app and measure performance from an end-user perspective.
Macrobenchmark uses UI Automator APIs to drive the UI and measure interactions.
For example, in startup benchmarks, you can use `onElement` to detect when UI
content is fully loaded, enabling you to measure [Time to Full Display
(TTFD)](https://developer.android.com/topic/performance/vitals/launch-time#time-full). In jank benchmarks, UI Automator APIs are used to scroll lists or
run animations to measure frame timings. Functions like `startActivity()` or
`startIntent()` are useful for getting the app into the correct state before
measurement begins.
When [generating Baseline Profiles](https://developer.android.com/topic/performance/baselineprofiles/create-baselineprofile), you automate your app's critical user
journeys (CUJs) to record which classes and methods require pre-compilation. UI
Automator is an ideal tool for writing these automation scripts. The modern
DSL's predicate-based element finding and built-in wait mechanisms (`onElement`)
lead to more robust and deterministic test execution compared to other methods.
This stability reduces flakiness and ensures that the generated Baseline Profile
accurately reflects the code paths executed during your most important user
flows.
## Advanced features
The following features are useful for more complex testing scenarios.
### Interact with multiple windows
The UI Automator APIs let you directly interact with and inspect UI
elements. This is particularly useful for scenarios involving multiple windows,
such as Picture-in-Picture (PiP) mode or split-screen layouts.
// Find the first window that is in Picture-in-Picture mode
val pipWindow = windows()
.first { it.isInPictureInPictureMode == true }
// Now you can interact with elements within that specific window
pipWindow.onElement { textAsString() == "Play" }.click()
### Screenshots and visual assertions
Capture screenshots of the entire screen, specific windows, or
individual UI elements directly within your tests. This is helpful for visual
regression testing and debugging.
uiautomator {
// Take a screenshot of the entire active window
val fullScreenBitmap: Bitmap = activeWindow().takeScreenshot()
fullScreenBitmap.saveToFile(File("/sdcard/Download/full_screen.png"))
// Take a screenshot of a specific UI element (e.g., a button)
val buttonBitmap: Bitmap = onElement { viewIdResourceName == "my_button" }.takeScreenshot()
buttonBitmap.saveToFile(File("/sdcard/Download/my_button_screenshot.png"))
// Example: Take a screenshot of a PiP window
val pipWindowScreenshot = windows()
.first { it.isInPictureInPictureMode == true }
.takeScreenshot()
pipWindowScreenshot.saveToFile(File("/sdcard/Download/pip_screenshot.png"))
}
The `saveToFile` extension function for Bitmap simplifies saving the captured
image to a specified path.
### Use ResultsReporter for debugging
The `ResultsReporter` helps you associate test artifacts, like screenshots,
directly with your test results in Android Studio for easier inspection and
debugging.
uiAutomator {
startApp("com.example.targetapp")
val reporter = ResultsReporter("MyTestArtifacts") // Name for this set of results
val file = reporter.addNewFile(
filename = "my_screenshot",
title = "Accessible button image" // Title that appears in Android Studio test results
)
// Take a screenshot of an element and save it using the reporter
onElement { textAsString() == "Accessible button" }
.takeScreenshot()
.saveToFile(file)
// Report the artifacts to instrumentation, making them visible in Android Studio
reporter.reportToInstrumentation()
}
## Migrate from older UI Automator versions
If you have existing UI Automator tests written with older API surfaces, use the
following table as a reference to migrate to the modern approach:
| Action type | Old UI Automator method | New UI Automator method |
|---|---|---|
| Entry point | `UiDevice.getInstance(InstrumentationRegistry.getInstrumentation())` | Wrap test logic in the `uiAutomator { ... }` scope. |
| Find UI elements | `device.findObject(By.res("com.example.app:id/my_button"))` | `onElement { viewIdResourceName == "my\_button" }` |
| Find UI elements | `device.findObject(By.text("Click Me"))` | `onElement { textAsString() == "Click Me" }` |
| Wait for idle UI | `device.waitForIdle()` | Prefer `onElement`'s built-in timeout mechanism; otherwise, `activeWindow().waitForStable()` |
| Find child elements | Manually nested `findObject` calls | `onElement().onElement()` chaining |
| Handle permission dialogs | `UiAutomator.registerWatcher()` | `watchFor(PermissionDialog)` |