From ad00deb1483f6c117fcb2201d5d7f29302dbb84d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ga=C3=ABtan=20Muller?= Date: Mon, 15 Apr 2024 09:04:31 +0200 Subject: [PATCH] Create Mkdocs config --- .gitignore | 8 +- androidx_test.md => docs/androidx_test.md | 6 +- .../automated-migration.md | 9 +- best-practices.md => docs/best-practices.md | 6 +- .../build-system-integration.md | 7 +- .../building-robolectric.md | 6 +- configuring.md => docs/configuring.md | 18 ++-- contributing.md => docs/contributing.md | 8 +- .../custom-test-runner.md | 6 +- .../device-configuration.md | 10 +- extending.md => docs/extending.md | 15 ++- getting-started.md => docs/getting-started.md | 14 ++- .../googleb5fedb8784be3ca2.html | 0 .../android-studio-configure-defaults.png | Bin .../android-studio-enable-unit-tests.png | Bin {images => docs/images}/favicon.ico | Bin .../images}/robolectric-stacked.png | Bin index.md => docs/index.md | 11 +- migrating.md => docs/migrating.md | 33 +++--- .../other-environments.md | 15 ++- .../using-add-on-modules.md | 6 +- .../using-qualifiers.md | 6 +- writing-a-test.md => docs/writing-a-test.md | 9 +- mkdocs.yml | 100 ++++++++++++++++++ 24 files changed, 181 insertions(+), 112 deletions(-) rename androidx_test.md => docs/androidx_test.md (98%) rename automated-migration.md => docs/automated-migration.md (95%) rename best-practices.md => docs/best-practices.md (96%) rename build-system-integration.md => docs/build-system-integration.md (96%) rename building-robolectric.md => docs/building-robolectric.md (97%) rename configuring.md => docs/configuring.md (96%) rename contributing.md => docs/contributing.md (95%) rename custom-test-runner.md => docs/custom-test-runner.md (93%) rename device-configuration.md => docs/device-configuration.md (98%) rename extending.md => docs/extending.md (93%) rename getting-started.md => docs/getting-started.md (87%) rename googleb5fedb8784be3ca2.html => docs/googleb5fedb8784be3ca2.html (100%) rename {images => docs/images}/android-studio-configure-defaults.png (100%) rename {images => docs/images}/android-studio-enable-unit-tests.png (100%) rename {images => docs/images}/favicon.ico (100%) rename {images => docs/images}/robolectric-stacked.png (100%) rename index.md => docs/index.md (92%) rename migrating.md => docs/migrating.md (95%) rename other-environments.md => docs/other-environments.md (93%) rename using-add-on-modules.md => docs/using-add-on-modules.md (96%) rename using-qualifiers.md => docs/using-qualifiers.md (97%) rename writing-a-test.md => docs/writing-a-test.md (98%) create mode 100644 mkdocs.yml diff --git a/.gitignore b/.gitignore index a370bee0f..85169bcb3 100644 --- a/.gitignore +++ b/.gitignore @@ -1,12 +1,6 @@ -_site -build .idea -.bundle -.sass-cache .DS_Store *.iml *.ipr *.iws -vendor -.jekyll-cache -.jekyll-metadata +site/ diff --git a/androidx_test.md b/docs/androidx_test.md similarity index 98% rename from androidx_test.md rename to docs/androidx_test.md index ccd0a8699..13b312c24 100644 --- a/androidx_test.md +++ b/docs/androidx_test.md @@ -1,8 +1,6 @@ --- -title: AndroidX Test -group: User Guide -order: 1 -redirect_from: "/activity-lifecycle/" +hide: +- footer --- # AndroidX Test diff --git a/automated-migration.md b/docs/automated-migration.md similarity index 95% rename from automated-migration.md rename to docs/automated-migration.md index 241632ec9..0cae12e26 100644 --- a/automated-migration.md +++ b/docs/automated-migration.md @@ -1,9 +1,8 @@ --- -title: Automated Migration -group: [hide] -order: 7 -toc: true -redirect_from: "/errorprone-refactorings/" +hide: +- footer +- navigation +- toc --- # Automated Migration diff --git a/best-practices.md b/docs/best-practices.md similarity index 96% rename from best-practices.md rename to docs/best-practices.md index 514a2c5cc..6a546b40b 100644 --- a/best-practices.md +++ b/docs/best-practices.md @@ -1,7 +1,7 @@ --- -title: Best Practices -group: User Guide -order: 8 +hide: +- footer +- toc --- # Best Practices diff --git a/build-system-integration.md b/docs/build-system-integration.md similarity index 96% rename from build-system-integration.md rename to docs/build-system-integration.md index 236d50174..4f9c030b9 100644 --- a/build-system-integration.md +++ b/docs/build-system-integration.md @@ -1,7 +1,7 @@ --- -title: Build System Integration -group: Customizing -order: 2 +hide: +- footer +- toc --- # Build System Integration @@ -13,6 +13,7 @@ This gives build system implementors the ability to perform manifest, asset and This supersedes Robolectric's support for merging multiple libraries specified via `@Config(libraries = {"lib1", "lib2"})` and `project.properties` support from legacy Eclipse ADT projects. Keys in the file: + * `android_merged_manifest`: Full path to the project's merged `AndroidManifest.xml` file. * `android_merged_resources`: Full path to the project's merged resources. * `android_merged_assets`: Full path to the project's merged assets. diff --git a/building-robolectric.md b/docs/building-robolectric.md similarity index 97% rename from building-robolectric.md rename to docs/building-robolectric.md index 7db45f09a..490fab446 100644 --- a/building-robolectric.md +++ b/docs/building-robolectric.md @@ -1,8 +1,6 @@ --- -title: Building Robolectric -group: Contributing -order: 1 -toc: true +hide: +- footer --- # Building Robolectric diff --git a/configuring.md b/docs/configuring.md similarity index 96% rename from configuring.md rename to docs/configuring.md index 27ccf2a21..9cf9bae98 100644 --- a/configuring.md +++ b/docs/configuring.md @@ -1,7 +1,6 @@ --- -title: Configuring Robolectric -group: User Guide -order: 2 +hide: +- footer --- # Configuring Robolectric @@ -15,7 +14,7 @@ To configure Robolectric for a single test class or method, use the TDD. There must be a better way. @@ -13,7 +11,6 @@ Running tests on an Android emulator or device is slow! Building, deploying, and ```java @RunWith(RobolectricTestRunner.class) public class MyActivityTest { - @Test public void clickingButton_shouldChangeMessage() { try (ActivityController controller = Robolectric.buildActivity(MyActivity.class)) { @@ -26,7 +23,7 @@ public class MyActivityTest { } } ``` -[» Getting Started...](/getting-started/) +[» Getting Started...](getting-started.md) ### Test APIs & Isolation diff --git a/migrating.md b/docs/migrating.md similarity index 95% rename from migrating.md rename to docs/migrating.md index d6a2e4e3f..35c587e88 100644 --- a/migrating.md +++ b/docs/migrating.md @@ -1,14 +1,12 @@ --- -title: Migration Guide -page_title: Robolectric Migration Guide -group: [hide] -order: 7 -toc: true +title: Robolectric Migration Guide +hide: +- footer --- ## Automated Migration -Robolectric provides an [automated migration tool](/automated-migration) to help keep your test suite up to date with Robolectric API changes. +Robolectric provides an [automated migration tool](automated-migration.md) to help keep your test suite up to date with Robolectric API changes. ## Migrating to 4.0 @@ -29,7 +27,7 @@ Put this in your `gradle.properties`: android.enableUnitTestBinaryResources=true ``` -If you have dependencies on `com.android.support.test`, switch them to `androidx.test`; see (Migrating to AndroidX)[https://developer.android.com/jetpack/androidx/migrate]. +If you have dependencies on `com.android.support.test`, switch them to `androidx.test`; see [Migrating to AndroidX](https://developer.android.com/jetpack/androidx/migrate). ### Deprecations @@ -41,7 +39,7 @@ If you have dependencies on `com.android.support.test`, switch them to `androidx | `ShadowApplication.getLatestPopupMenu()` | `ShadowPopupMenu.getLatestPopupMenu()` | | `ShadowLooper.getShadowMainLooper()` | `shadowOf(Looper.getMainLooper())` | -The [automatic migration tool](#AutomatedMigration) includes a migration to help with this. +The [automatic migration tool](#automated-migration) includes a migration to help with this. * `@Config(manifest=...)` is no longer supported when using binary resources mode. Instead, Robolectric always uses the merged manifest generated by the Android toolchain. If your test was using a custom manifest you'll need to adapt it to not rely on that. * `@Config(resourceDir=...)`, `@Config(assetDir=...)`, and `@Config(packageName...)` are no longer supported in binary resources mode. @@ -55,7 +53,7 @@ Prior to 4.0, it was possible (but ill-advised) to get the shadow for an Android | `shadowOf(activity).finish();` | `activity.finish()` | | `ShadowSystemClock.currentTimeMillis();` | `SystemClock.currentTimeMillis();` | -The [automatic migration tool](#AutomatedMigration) will fix most of these for you. +The [automatic migration tool](#automated-migration) will fix most of these for you. ### androidx.test @@ -71,10 +69,10 @@ Robolectric 4.0 includes initial support for [`androidx.test` APIs](https://deve Robolectric 4.0 replaces its old home-grown resource handling code with a direct adaptation of Android's resource handling code, using the full Android toolchain. This greatly improves fidelity to the behavior of a real Android device, but if your tests were relying on quirks of the old code, you may need to fix your tests. Some likely issues include: -* `android.view.InflateException: Binary XML file line #3: Failed to resolve attribute at index 17: TypedValue{t=0x2/d=0x7f01000e a=-1}`
This happens when your activity is using a theme that lacks values for certain attributes used by layouts. Make sure you've specified an appropriate theme for your activities in the manifest. +* `android.view.InflateException: Binary XML file line #3: Failed to resolve attribute at index 17: TypedValue{t=0x2/d=0x7f01000e a=-1}`
This happens when your activity is using a theme that lacks values for certain attributes used by layouts. Make sure you've specified an appropriate theme for your activities in the manifest. -## Migrating to 3.6 +## Migrating to 3.6 Previously Robolectric's Display and DisplayMetrics dimensions defaulted to 480px x 800px, regardless of screen size and density. Now they match the requested configuration, which defaults to 320dp x 470dp mdpi. Tests which rely on the old dimensions for layouts, pixel math, etc. can be modified for new dimensions, or by pinning them to the old size: `@Config(qualifiers = "w480dp-h800dp")`. @@ -82,7 +80,7 @@ Previously Robolectric's Display and DisplayMetrics dimensions defaulted to 480p | ------------------------------------------------------- | -------------------------------------------------------------- | | `Shadow.newInstanceOf(Display.class)` | `ShadowDisplay.getDefaultDisplay()` | -## Migrating to 3.4 +## Migrating to 3.4 ### Dependencies Robolectric tests should now be compiled with Java 8 and Android API 26. @@ -106,7 +104,7 @@ The deprecated and redundant `attach()` method has been removed from `ActivityCo --- -## Migrating to 3.3 +## Migrating to 3.3 ### Moved classes To simplify classloader logic and clean up packages, some classes have moved. The old class locations are `@Deprecated` and will be removed in 3.4. @@ -130,6 +128,7 @@ To simplify classloader logic and clean up packages, some classes have moved. Th ### PackageManager We have begun the process of switching from using a subclass of `PackageManager` towards `PackageManager` being implemented by a standard shadow, as we do for the rest of the framework. This is for a number of reasons: + * It is more consistent with the way other framework code is handled. * A shadow will allow users' tests to build against any version of Android. * Switching to a shadow will allow us to defer parsing the manifest until the test or code under test makes calls to the `PackageManager`. @@ -180,12 +179,12 @@ RobolectricPackageManager ### New Gradle integration -Starting with Robolectric 3.3 + Android Studio 3.0 alpha 5 we've included better integration with the tool chain. Resources, assets and `AndroidManifest.xml` are treated as first class citizens and processed by the build system for correctness, performance and stability between releases. Read more [here](http://robolectric.org/getting-started/). +Starting with Robolectric 3.3 + Android Studio 3.0 alpha 5 we've included better integration with the tool chain. Resources, assets and `AndroidManifest.xml` are treated as first class citizens and processed by the build system for correctness, performance and stability between releases. Read more [here](getting-started.md). --- -## Migrating to 3.2 +## Migrating to 3.2 ### Programmatic Configuration If you were providing custom configuration by subclassing and overriding methods on `RobolectricTestRunner`, you'll need to make some changes. @@ -221,7 +220,7 @@ If you are using `robolectric.properties` file to configure all tests, the expec --- -## Migrating to 3.1 +## Migrating to 3.1 ### Changes * To construct Android components such as `Activity`, `Service` and `ContentProvider` classes you must now use the Robolectric APIs such as `Robolectric.buildService()`, `Robolectric.buildActivity()` or `Robolectric.buildContentProvider()` or the `setup*()` variants; you should not create new instances of these classes yourself. Calling these methods will create an instance of the component and attach its base context. This is now necessary as we've removed code shadowing `Context` and `ContextWrapper` in favor of using real framework code to improve fidelity. @@ -258,7 +257,7 @@ Robolectric.setupContentProvider(MyContentProvider.class); --- -## Migrating to 3.0 +## Migrating to 3.0 ### New Features diff --git a/other-environments.md b/docs/other-environments.md similarity index 93% rename from other-environments.md rename to docs/other-environments.md index bee4965a1..5a1703800 100644 --- a/other-environments.md +++ b/docs/other-environments.md @@ -1,13 +1,10 @@ --- -title: Other Environments -page_title: Using Robolectric with other build environments. -group: Setup -order: 2 -toc: true -group: [hide] +title: Using Robolectric with other build environments +hide: +- footer +- navigation --- - ## Android Studio + Gradle (AGP < 3.0) In earlier versions you must specify the `constants` field which points to the `BuildConfig.class` generated by Gradle. Robolectric uses the constants in the class to compute the output paths used by Gradle when building your project. Without these values, Robolectric will not be able to find your merged manifest, resources, or assets. This will cease to work in the future so we strongly recomend migrating to the new API. @@ -28,13 +25,13 @@ public class SandwichTest { Robolectric works with Android Studio 1.1.0 or newer. Simply follow the instructions above for working with Gradle. For versions of Android Studio older than 2.0.0, enable the unit test support in the "Build Variants" tab and run your test. As of Android Studio 2.0.0, the test artifacts feature is enabled by default, and the setting to enable/disable test artifacts can be found in File Menu -> Settings -> Build, Execution, Deployment -> Build Tools -> Gradle -> Experimental. -![Android Enable Unit Tests](/images/android-studio-enable-unit-tests.png) +![Android Enable Unit Tests](images/android-studio-enable-unit-tests.png) ### Updating JUnit run configurations You will probably also need to configure the default JUnit test runner configuration in order to work around a bug where Android Studio does not set the working directory to the module being tested. This can be accomplished by editing the run configurations, `Defaults -> Android JUnit` and changing the working directory value to `$MODULE_DIR$`. -![Android Studio Configure Defaults](/images/android-studio-configure-defaults.png) +![Android Studio Configure Defaults](images/android-studio-configure-defaults.png) Note that if you already have existing JUnit configurations (`Android JUnit` in the root of the tree), you must do the same change as described above for all of them. diff --git a/using-add-on-modules.md b/docs/using-add-on-modules.md similarity index 96% rename from using-add-on-modules.md rename to docs/using-add-on-modules.md index c9a65a721..d12ba9604 100644 --- a/using-add-on-modules.md +++ b/docs/using-add-on-modules.md @@ -1,7 +1,7 @@ --- -title: Using Add-On Modules -group: User Guide -order: 4 +hide: +- footer +- toc --- # Using Add-On Modules diff --git a/using-qualifiers.md b/docs/using-qualifiers.md similarity index 97% rename from using-qualifiers.md rename to docs/using-qualifiers.md index 946554dba..72d8a3ad5 100644 --- a/using-qualifiers.md +++ b/docs/using-qualifiers.md @@ -1,7 +1,7 @@ --- -title: Using Qualified Resources -group: User Guide -order: 3 +hide: +- footer +- toc --- # Using Qualified Resources diff --git a/writing-a-test.md b/docs/writing-a-test.md similarity index 98% rename from writing-a-test.md rename to docs/writing-a-test.md index d2d60be21..7aa526bde 100644 --- a/writing-a-test.md +++ b/docs/writing-a-test.md @@ -1,7 +1,7 @@ --- -title: Writing Your First Test -group: Setup -order: 2 +hide: +- footer +- toc --- # Writing Your First Test @@ -20,7 +20,6 @@ Let's say you have an activity layout that represents a welcome screen: android:text="Login" android:layout_width="wrap_content" android:layout_height="wrap_content"/> - ``` @@ -28,7 +27,6 @@ We want to write a test that asserts that when a user clicks on a button, the ap ```java public class WelcomeActivity extends Activity { - @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); @@ -50,7 +48,6 @@ In order to test this, we can check that when a user clicks on the "Login" butto ```java @RunWith(RobolectricTestRunner.class) public class WelcomeActivityTest { - @Test public void clickingLogin_shouldStartLoginActivity() { try (ActivityController controller = Robolectric.buildActivity(WelcomeActivity.class)) { diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 000000000..ed2e190a8 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,100 @@ +site_name: Robolectric +site_description: "test-drive your Android code" +site_url: "https://robolectric.org" +copyright: "©2010-2023. All rights reserved." +repo_url: "https://github.com/robolectric/robolectric" +repo_name: Robolectric + +theme: + name: material + favicon: images/favicon.ico + logo: images/robolectric-stacked.png + icon: + repo: fontawesome/brands/github + palette: + # Palette toggle for light mode + - media: "(prefers-color-scheme: light)" + scheme: default + primary: green + toggle: + icon: material/weather-night + name: "Switch to dark mode" + # Palette toggle for dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: green + toggle: + icon: material/weather-sunny + name: "Switch to light mode" + features: + - content.code.copy + - navigation.footer + - navigation.sections + - navigation.tabs + +markdown_extensions: + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences + +extra: + analytics: + provider: google + property: "UA-19269905-2" + robolectric: + version: + current: "4.12" + preview: "4.13-SNAPSHOT" + snapshot: "4.13-SNAPSHOT" + social: + - name: "GitHub Project" + icon: fontawesome/brands/github + link: "http://github.com/robolectric/robolectric" + - name: "robolectric@googlegroups.com" + icon: fontawesome/regular/envelope + link: "http://groups.google.com/group/robolectric" + - name: "@Robolectric" + icon: fontawesome/brands/x-twitter + link: "https://x.com/robolectric" + +nav: + - Setup: + - Getting Started: getting-started.md + - Writing Your First Test: writing-a-test.md + - User Guide: + - AndroidX Test: androidx_test.md + - Configuring Robolectric: configuring.md + - Device Configuration: device-configuration.md + - Using Qualified Resources: using-qualifiers.md + - Using Add-On Modules: using-add-on-modules.md + - Best Practices: best-practices.md + - Customizing: + - Build System Integration: build-system-integration.md + - Customizing the Test Runner: custom-test-runner.md + - Contributing: + - Building Robolectric: building-robolectric.md + - Contributor Guidelines: contributing.md + - Shadows: extending.md + - Resources: + - Migration Guide: migrating.md + - GitHub: https://github.com/robolectric/robolectric/ + - Release Notes: https://github.com/robolectric/robolectric/releases/ + - Issues: https://github.com/robolectric/robolectric/issues/ + - Javadoc: + - 4.12: /javadoc/4.12/ + - 4.11: /javadoc/4.11/ + - 4.10: /javadoc/4.10/ + - 4.9: /javadoc/4.9/ + - 4.8: /javadoc/4.8/ + - 4.7: /javadoc/4.7/ + - 4.6: /javadoc/4.6/ + - 4.5: /javadoc/4.5/ + - 4.4: /javadoc/4.4/ + - 4.3: /javadoc/4.3/ + - 4.2: /javadoc/4.2/ + - 4.1: /javadoc/4.1/ + - 4.0: /javadoc/4.0/