Skip to content

Commit

Permalink
Extract links some documentation pages (robolectric#336)
Browse files Browse the repository at this point in the history 
This PR extracts the links from the following pages:
- `configuring`
- `custom-test-runner`
- `device-configuration`
- `extending`
- `getting-started`
- `index`
- `using-add-on-modules`
- `using-qualifiers`
- `writing-a-test`
  • Loading branch information
@MGaetan89
MGaetan89 authored Oct 23, 2024
1 parent 76e4346 commit 6a0cb23
Show file tree
Hide file tree
Showing 9 changed files with 244 additions and 74 deletions.
76 changes: 56 additions & 20 deletions docs/configuring.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,9 @@ Several aspects of Robolectric's behavior can be configured at runtime, using ei

### `@Config` annotation

To configure Robolectric for a single test class or method, use the [`@Config`](javadoc/latest/org/robolectric/annotation/Config.html) annotation on the desired class or method.
Annotations applied on methods take precedence over the ones at the class level.
To configure Robolectric for a single test class or method, use the
[`@Config`][config-documentation] annotation on the desired class or method. Annotations applied on
methods take precedence over the ones at the class level.

Base classes are also searched for annotations. So if you find yourself specifying the same values on a large number of tests, you can create a base class and move your `@Config` annotation to that class.

Expand Down Expand Up @@ -44,20 +45,24 @@ shadows=com.mycompany.ShadowFoo,com.mycompany.ShadowBar
```

> [!NOTE]
> Prior to [Robolectric 3.1.3](https://github.com/robolectric/robolectric/releases/tag/robolectric-3.1.3), only a top-level `robolectric.properties` file may be specified.
> Prior to [Robolectric 3.1.3][robolectric-3.1.3-release], only a top-level `robolectric.properties`
> file may be specified.
### Global Configuration

If you wish to change the default for any configurable value for all your tests, you can provide a [`GlobalConfigProvider`](javadoc/latest/org/robolectric/pluginapi/config/GlobalConfigProvider.html) service implementation.
If you wish to change the default for any configurable value for all your tests, you can provide a
[`GlobalConfigProvider`][global-config-provider] service implementation.

## Configurables

The following examples show how to handle common configuration tasks. For clarity, `@Config` annotations are used, but any of these values may also be configured using properties files.

### Configure SDK Level

By default, Robolectric will run your code against the `targetSdk` specified in your module's `build.gradle`/`build.gradle.kts` or `AndroidManifest.xml` file.
If you want to test your code under a different SDK, you can specify the desired SDK(s) using the [`sdk`](javadoc/latest/org/robolectric/annotation/Config.html#sdk()), [`minSdk`](javadoc/latest/org/robolectric/annotation/Config.html#minSdk()) and [`maxSdk`](javadoc/latest/org/robolectric/annotation/Config.html#maxSdk()) config properties:
By default, Robolectric will run your code against the `targetSdk` specified in your module's
`build.gradle`/`build.gradle.kts` or `AndroidManifest.xml` file. If you want to test your code under
a different SDK, you can specify the desired SDK(s) using the [`sdk`][config-sdk],
[`minSdk`][config-min-sdk] and [`maxSdk`][config-max-sdk] config properties:

=== "Java"

Expand Down Expand Up @@ -111,13 +116,16 @@ Note that `sdk` and `minSdk`/`maxSdk` may not be specified in the same `@Config`
however, `minSdk` and `maxSdk` may be specified together. If any of them is present, they override any SDK specification from a less-specific configuration location.

> [!NOTE]
> Prior to [Robolectric 3.2](https://github.com/robolectric/robolectric/releases/tag/robolectric-3.2), `minSdk` and `maxSdk` are ignored, and [`NEWEST_SDK`](javadoc/latest/org/robolectric/annotation/Config.html#NEWEST_SDK), [`OLDEST_SDK`](javadoc/latest/org/robolectric/annotation/Config.html#OLDEST_SDK), and [`TARGET_SDK`](javadoc/latest/org/robolectric/annotation/Config.html#TARGET_SDK) are not supported.
> Also, only integers corresponding to API levels may be specified in a properties file.
> Prior to [Robolectric 3.2][robolectric-3.2-release], `minSdk` and `maxSdk` are ignored, and
> [`NEWEST_SDK`][config-newest-sdk], [`OLDEST_SDK`][config-oldest-sdk], and
> [`TARGET_SDK`][config-target-sdk] are not supported. Also, only integers corresponding to API
> levels may be specified in a properties file.
### Configure `Application` class

Robolectric will attempt to create an instance of your [`Application`](https://developer.android.com/reference/android/app/Application) class
as specified in the `AndroidManifest`. If you want to provide a custom implementation, you can specify it by setting:
Robolectric will attempt to create an instance of your [`Application`][application-documentation]
class as specified in the `AndroidManifest`. If you want to provide a custom implementation, you can
specify it by setting:

=== "Java"

Expand Down Expand Up @@ -189,15 +197,17 @@ Some additional options can be configured globally by setting these system prope
| `robolectric.dependency.repo.password` | Password of the repository that you defined in `robolectric.dependency.repo.url`. | `null` |
| `robolectric.logging.enabled` | Set to `true` to enable debug logging. | `false` |

Since [Robolectric 4.9.1](https://github.com/robolectric/robolectric/releases/tag/robolectric-4.9.1), you can now add these parameters :
Since [Robolectric 4.9.1][robolectric-4.9.1-release], you can now add these parameters:

| Property name | Description | Default value |
|-----|-----|-----|
| `robolectric.dependency.proxy.host` | Set the host of the proxy to use for the runtime dependencies. | `null` |
| `robolectric.dependency.proxy.port` | Set the port number of the proxy to use for the runtime dependencies. | `0` |

When using Gradle, you can configure the System Properties for unit tests with the `android.testOptions.unitTests.all` block (see [here](https://developer.android.com/studio/test/advanced-test-setup#configure-gradle-test-options)).
For example, to override the Maven repository URL and ID to download the runtime dependencies from a repository other than Maven Central:
When using Gradle, you can configure the System Properties for unit tests with the
`android.testOptions.unitTests.all` block (see [here][configure-gradle-test-options]). For example,
to override the Maven repository URL and ID to download the runtime dependencies from a repository
other than Maven Central:

=== "Groovy"

Expand Down Expand Up @@ -243,10 +253,36 @@ For example, to override the Maven repository URL and ID to download the runtime

## `ConscryptMode`

Starting with [Robolectric 4.9](https://github.com/robolectric/robolectric/releases/tag/robolectric-4.9), Robolectric can either use Conscrypt and BouncyCastle or just BouncyCastle as the security provider.
In order to migrate tests over time, there is a [`ConscryptMode`](javadoc/latest/org/robolectric/annotation/ConscryptMode.html) annotation that controls whether Conscrypt is loaded as the default security provider with BouncyCastle as backup.

- If [`ConscryptMode.Mode`](javadoc/latest/org/robolectric/annotation/ConscryptMode.Mode.html) is [`ON`](javadoc/latest/org/robolectric/annotation/ConscryptMode.Mode.html#ON), it will install Conscrypt and BouncyCastle.
- If [`ConscryptMode.Mode`](javadoc/latest/org/robolectric/annotation/ConscryptMode.Mode.html) is [`OFF`](javadoc/latest/org/robolectric/annotation/ConscryptMode.Mode.html#OFF), it will only install BouncyCastle.

This is closer to to the way that it works on [real android](https://cs.android.com/android/platform/superproject/+/android-13.0.0_r1:libcore/ojluni/src/main/java/java/security/Security.java;l=134-137). Robolectric will search for a requested security primitive from Conscrypt first. If it does not support it, Robolectric will try BouncyCastle second.
Starting with [Robolectric 4.9][robolectric-4.9-release], Robolectric can either use Conscrypt and
BouncyCastle or just BouncyCastle as the security provider. In order to migrate tests over time,
there is a [`ConscryptMode`][conscrypt-mode] annotation that controls whether Conscrypt is loaded as
the default security provider with BouncyCastle as backup.

- If [`ConscryptMode.Mode`][conscrypt-mode-mode] is [`ON`][conscrypt-mode-mode-on], it will install
Conscrypt and BouncyCastle.
- If [`ConscryptMode.Mode`][conscrypt-mode-mode] is [`OFF`][conscrypt-mode-mode-off], it will only
install BouncyCastle.

This is closer to the way that it works on [real android][android-security]. Robolectric will search
for a requested security primitive from Conscrypt first. If it does not support it, Robolectric will
try BouncyCastle second.

[android-security]: https://cs.android.com/android/platform/superproject/+/android-13.0.0_r1:libcore/ojluni/src/main/java/java/security/Security.java;l=134-137
[application-documentation]: https://developer.android.com/reference/android/app/Application
[config-documentation]: javadoc/latest/org/robolectric/annotation/Config.html
[config-max-sdk]: javadoc/latest/org/robolectric/annotation/Config.html#maxSdk()
[config-min-sdk]: javadoc/latest/org/robolectric/annotation/Config.html#minSdk()
[config-newest-sdk]: javadoc/latest/org/robolectric/annotation/Config.html#NEWEST_SDK
[config-oldest-sdk]: javadoc/latest/org/robolectric/annotation/Config.html#OLDEST_SDK
[config-target-sdk]: javadoc/latest/org/robolectric/annotation/Config.html#TARGET_SDK
[config-sdk]: javadoc/latest/org/robolectric/annotation/Config.html#sdk()
[configure-gradle-test-options]: https://developer.android.com/studio/test/advanced-test-setup#configure-gradle-test-options
[conscrypt-mode]: javadoc/latest/org/robolectric/annotation/ConscryptMode.html
[conscrypt-mode-mode]: javadoc/latest/org/robolectric/annotation/ConscryptMode.Mode.html
[conscrypt-mode-mode-off]: javadoc/latest/org/robolectric/annotation/ConscryptMode.Mode.html#OFF
[conscrypt-mode-mode-on]: javadoc/latest/org/robolectric/annotation/ConscryptMode.Mode.html#ON
[global-config-provider]: javadoc/latest/org/robolectric/pluginapi/config/GlobalConfigProvider.html
[robolectric-3.1.3-release]: https://github.com/robolectric/robolectric/releases/tag/robolectric-3.1.3
[robolectric-3.2-release]: https://github.com/robolectric/robolectric/releases/tag/robolectric-3.2
[robolectric-4.9-release]: https://github.com/robolectric/robolectric/releases/tag/robolectric-4.9
[robolectric-4.9.1-release]: https://github.com/robolectric/robolectric/releases/tag/robolectric-4.9.1
18 changes: 11 additions & 7 deletions docs/custom-test-runner.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,17 @@ hide:

# Customizing the Test Runner

There are several situations where you want to customize Robolectric's test runner to perform some operation
before all tests are run, or even before each test method is run. One good example is initializing a dependency
injection framework with a different set of dependencies for your test. Fortunately, Robolectric has a way to
hook into the test lifecycle. If you define an [`Application`](https://developer.android.com/reference/android/app/Application)
class in your `AndroidManifest.xml` file, Robolectric will automatically try and load a test version of your
`Application` class first.
There are several situations where you want to customize Robolectric's test runner to perform some
operation before all tests are run, or even before each test method is run. One good example is
initializing a dependency injection framework with a different set of dependencies for your test.
Fortunately, Robolectric has a way to hook into the test lifecycle. If you define an
[`Application`][application-documentation] class in your `AndroidManifest.xml` file, Robolectric
will automatically try and load a test version of your `Application` class first.

## Hilt

If you're using Hilt, you can check the official [Robolectric testing integration](https://dagger.dev/hilt/robolectric-testing.html) guide from Hilt.
If you're using Hilt, you can check the official
[Robolectric testing integration][dagger-hilt-robolectric] guide from Hilt.

[application-documentation]: https://developer.android.com/reference/android/app/Application
[dagger-hilt-robolectric]: https://dagger.dev/hilt/robolectric-testing.html
43 changes: 36 additions & 7 deletions docs/device-configuration.md
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,13 @@
# Device Configuration

Robolectric makes it easy to simulate a variety of device configurations. In particular, the properties that make up the [`Configuration`](https://developer.android.com/reference/android/content/res/Configuration) class can be specified at the test method, test class, package, or suite level, as described [here](configuring.md).
Robolectric makes it easy to simulate a variety of device configurations. In particular, the
properties that make up the [`Configuration`][configuration-documentation] class can be specified at
the test method, test class, package, or suite level, as described [here](configuring.md).

## Specifying device configuration

The Android device configuration can be specified using the [`qualifiers`](javadoc/latest/org/robolectric/annotation/Config.html#qualifiers()) [`@Config`](javadoc/latest/org/robolectric/annotation/Config.html) argument:
The Android device configuration can be specified using the [`qualifiers`][config-qualifiers]
[`@Config`][config-documentation] argument:

=== "Java"

Expand All @@ -24,7 +27,12 @@ The Android device configuration can be specified using the [`qualifiers`](javad
}
```

From [version 3.6](https://github.com/robolectric/robolectric/releases/tag/robolectric-3.6) on, Robolectric parses the `qualifiers` property according to the rules set forth [here](https://developer.android.com/guide/topics/resources/providing-resources.html#QualifierRules) (but with no preceding directory name), and sets up the Android simulation environment with a corresponding configuration. The system's `Configuration`, [`Display`](https://developer.android.com/reference/android/view/Display) and [`DisplayMetrics`](https://developer.android.com/reference/android/hardware/display/DisplayManager) objects will all reflect the specified configuration, the locale will be set, and appropriate resources will be selected.
From [version 3.6][robolectric-3.6-release] on, Robolectric parses the `qualifiers` property
according to the rules set forth [here][android-resources-qualifier-rules] (but with no preceding
directory name), and sets up the Android simulation environment with a corresponding configuration.
The system's `Configuration`, [`Display`][display-documentation] and
[`DisplayMetrics`][display-metrics-documentation] objects will all reflect the specified
configuration, the locale will be set, and appropriate resources will be selected.

For unspecified properties, Robolectric picks consistent values based on the properties that have been specified, or uses default values as follows:

Expand Down Expand Up @@ -108,7 +116,8 @@ Values for unspecified properties are calculated, and rules are applied, after a

## Changing device configuration

The device configuration can be changed within a test using [`RuntimeEnvironment.setQualifiers()`](javadoc/latest/org/robolectric/RuntimeEnvironment.html#setQualifiers(java.lang.String)):
The device configuration can be changed within a test using
[`RuntimeEnvironment.setQualifiers()`][runtime-environment-set-qualifiers]:

=== "Java"

Expand Down Expand Up @@ -142,10 +151,30 @@ The device configuration can be changed within a test using [`RuntimeEnvironment

The string parameter to `RuntimeEnvironment.setQualifiers()` has the same rules as `Config.qualifiers`.

Note that `RuntimeEnvironment.setQualifiers()` updates the system and application resources with the new configuration, but does not trigger any action on extant activities or other components. [`ActivityController.configurationChange()`](javadoc/latest/org/robolectric/android/controller/ActivityController.html#configurationChange(android.content.res.Configuration)) can be used to simulate the sequence of events that take place on a device when its configuration changes.
Note that `RuntimeEnvironment.setQualifiers()` updates the system and application resources with the
new configuration, but does not trigger any action on extant activities or other components.
[`ActivityController.configurationChange()`][activity-controller-configuration-change] can be used
to simulate the sequence of events that take place on a device when its configuration changes.

If the [`Activity`](https://developer.android.com/reference/android/app/Activity) is configured to handle the configuration changes, `ActivityController.configurationChange()` will call the `Activity`’s `onConfigurationChanged()` method. If not, `ActivityController` destroys and recreates the `Activity`.
If the [`Activity`][activity-documentation] is configured to handle the configuration changes,
`ActivityController.configurationChange()` will call the `Activity`’s `onConfigurationChanged()`
method. If not, `ActivityController` destroys and recreates the `Activity`.

## Simulating displays

Robolectric allows display properties to be changed during a test using setters on [`ShadowDisplay`](javadoc/latest/org/robolectric/shadows/ShadowDisplay.html). Multiple displays can be simulated using APIs on [`ShadowDisplayManager`](javadoc/latest/org/robolectric/shadows/ShadowDisplayManager.html).
Robolectric allows display properties to be changed during a test using setters on
[`ShadowDisplay`][shadow-display]. Multiple displays can be simulated using APIs on
[`ShadowDisplayManager`][shadow-display-manager].

[activity-controller-configuration-change]: javadoc/latest/org/robolectric/android/controller/ActivityController.html#configurationChange(android.content.res.Configuration)
[activity-documentation]: https://developer.android.com/reference/android/app/Activity
[android-resources-qualifier-rules]: https://developer.android.com/guide/topics/resources/providing-resources.html#QualifierRules
[config-documentation]: javadoc/latest/org/robolectric/annotation/Config.html
[config-qualifiers]: javadoc/latest/org/robolectric/annotation/Config.html#qualifiers()
[configuration-documentation]: https://developer.android.com/reference/android/content/res/Configuration
[display-documentation]: https://developer.android.com/reference/android/view/Display
[display-metrics-documentation]: https://developer.android.com/reference/android/util/DisplayMetrics
[robolectric-3.6-release]: https://github.com/robolectric/robolectric/releases/tag/robolectric-3.6
[runtime-environment-set-qualifiers]: javadoc/latest/org/robolectric/RuntimeEnvironment.html#setQualifiers(java.lang.String)
[shadow-display]: javadoc/latest/org/robolectric/shadows/ShadowDisplay.html
[shadow-display-manager]: javadoc/latest/org/robolectric/shadows/ShadowDisplayManager.html
Loading

0 comments on commit 6a0cb23

Please sign in to comment.