Kaspresso项目中的WRITE_EXTERNAL_STORAGE权限问题分析与解决方案

问题背景

在Android开发中，文档本地化截图测试是一个常见的需求。Kaspresso作为一款优秀的Android测试框架，提供了DocLocScreenshotTestCase来简化这一过程。然而，在Android 10（API 29）及以上版本的设备上运行时，开发者可能会遇到WRITE_EXTERNAL_STORAGE权限无法授予的问题。

问题现象

当在API 29+的设备上执行DocLocScreenshotTestCase测试时，测试会失败并抛出异常：

Permission: android.permission.WRITE_EXTERNAL_STORAGE cannot be granted!
junit.framework.AssertionFailedError: Failed to grant permissions

技术分析

权限模型变更

从Android 10开始，Google引入了Scoped Storage（分区存储）机制，对外部存储权限模型做出了重大调整：

1. WRITE_EXTERNAL_STORAGE权限的作用范围被大幅缩小
2. 应用默认只能访问自己的专有目录（App-specific目录）
3. 访问媒体文件需要改用新的MediaStore API

Kaspresso的兼容性问题

DocLocScreenshotTestCase默认请求WRITE_EXTERNAL_STORAGE权限，这在旧版Android上是可行的，但在新版本上会遇到限制：

1. 即使声明了权限，系统也可能拒绝授予
2. 测试框架尝试通过GrantPermissionRule授予权限时会失败
3. 需要额外的READ_EXTERNAL_STORAGE权限配合

解决方案

方案一：正确声明和请求权限

1. 在AndroidManifest.xml中声明权限：

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>

2. 在测试类中添加权限请求规则：

@get:Rule
val runtimePermissionRule = GrantPermissionRule.grant(
    Manifest.permission.WRITE_EXTERNAL_STORAGE,
    Manifest.permission.READ_EXTERNAL_STORAGE
)

方案二：适配Scoped Storage（推荐）

对于长期维护的项目，建议适配新的存储访问方式：

1. 使用Context.getExternalFilesDir()获取应用专属存储目录
2. 修改Kaspresso的截图保存逻辑，将文件存储在应用专属目录
3. 或者改用MediaStore API保存截图到公共媒体目录

方案三：临时解决方案

如果只是需要快速解决问题，可以在AndroidManifest.xml中添加：

<application
    android:requestLegacyExternalStorage="true"
    ...>

这将临时禁用Scoped Storage，但需要注意：

1. 仅对targetSdkVersion 29的应用有效
2. 在Android 11+设备上会完全失效
3. 不是长期解决方案

最佳实践建议

1. 对于新项目，建议直接实现Scoped Storage适配
2. 对于维护中的项目，可以先采用方案一+方案三的组合
3. 定期检查测试用例在最新Android版本上的兼容性
4. 考虑将截图保存在内部存储或应用专属外部存储中

总结