archive-gh-me/android-samples
1
0
Fork 0
mirror of https://github.com/googlemaps/android-samples.git synced 2025-12-08 18:02:20 +00:00
Code Issues Projects Releases Wiki Activity

docs(test): Add Javadoc and KDoc to custom Truth subjects

Browse Source 
Adds comprehensive documentation to the `LatLngSubject` and `LatLngBoundsSubject` classes for both the Java and Kotlin test sources. This improves their value as a learning resource for developers by explaining their purpose, usage, and the underlying logic for handling geospatial comparisons with tolerance.
This commit is contained in:
dkhawk 2025-10-21 16:41:07 -06:00
parent 7343487840
commit 7ee3db04f3
4 changed files with 79 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
ApiDemos/project/java-app/src/androidTest/java/com/example/mapdemo/truth/LatLngBoundsSubject.java
View File

@ -6,6 +6,11 @@ import com.google.common.truth.FailureMetadata;
import com.google.common.truth.Subject;
import com.google.common.truth.Truth;
/**
* A custom Truth subject for asserting properties of {@link LatLngBounds} objects.
* <p>
* To use, static import {@link #assertThat(LatLngBounds)} and call assertions on the subject.
*/
public final class LatLngBoundsSubject extends Subject {
private final LatLngBounds actual;
private static final double TOLERANCE = 1e-5;
@ -15,14 +20,24 @@ public final class LatLngBoundsSubject extends Subject {
this.actual = actual;
}
/**
* The factory for creating {@link LatLngBoundsSubject} instances.
*/
public static Factory<LatLngBoundsSubject, LatLngBounds> latLngBounds() {
return LatLngBoundsSubject::new;
}
/**
* Creates a {@link LatLngBoundsSubject} for asserting on the given {@link LatLngBounds}.
*/
public static LatLngBoundsSubject assertThat(LatLngBounds actual) {
return Truth.assertAbout(latLngBounds()).that(actual);
}
/**
* Asserts that the given {@link LatLng} is contained within the actual bounds, allowing for
* a small tolerance to account for floating-point inaccuracies.
*/
public void containsWithTolerance(LatLng expected) {
boolean contains = actual.southwest.latitude - TOLERANCE <= expected.latitude &&
expected.latitude <= actual.northeast.latitude + TOLERANCE &&
@ -32,12 +47,17 @@ public final class LatLngBoundsSubject extends Subject {
}
}
/**
* Checks if a longitude is within the bounds, correctly handling cases where the bounds
* cross the antimeridian (e.g., from 160 to -160).
*/
private boolean isLongitudeWithinBounds(double longitude, LatLngBounds bounds) {
if (bounds.southwest.longitude <= bounds.northeast.longitude) {
// Standard case (e.g., from 10 to 20).
return longitude >= bounds.southwest.longitude - TOLERANCE &&
longitude <= bounds.northeast.longitude + TOLERANCE;
} else {
// The bounds cross the antimeridian.
// Case where the bounds cross the antimeridian (e.g., from 160 to -160).
return longitude >= bounds.southwest.longitude - TOLERANCE ||
longitude <= bounds.northeast.longitude + TOLERANCE;
}

21
ApiDemos/project/java-app/src/androidTest/java/com/example/mapdemo/truth/LatLngSubject.java
View File

@ -1,11 +1,20 @@
package com.example.mapdemo.truth;
import com.google.android.gms.maps.model.LatLng;
import com.google.android.gms.maps.model.LatLngBounds;
import com.google.common.truth.FailureMetadata;
import com.google.common.truth.Subject;
import com.google.common.truth.Truth;
/**
* A custom Truth subject for asserting properties of {@link LatLng} objects.
* <p>
* To use, static import {@link #assertThat(LatLng)} and call assertions on the subject.
* <pre>{@code
* LatLng actual = new LatLng(10.0, 20.0);
* LatLng expected = new LatLng(10.000001, 20.000001);
* assertThat(actual).isNear(expected);
* }</pre>
*/
public final class LatLngSubject extends Subject {
private final LatLng actual;
private static final double TOLERANCE = 1e-6;
@ -15,14 +24,24 @@ public final class LatLngSubject extends Subject {
this.actual = actual;
}
/**
* The factory for creating {@link LatLngSubject} instances.
*/
public static Factory<LatLngSubject, LatLng> latLngs() {
return LatLngSubject::new;
}
/**
* Creates a {@link LatLngSubject} for asserting on the given {@link LatLng}.
*/
public static LatLngSubject assertThat(LatLng actual) {
return Truth.assertAbout(latLngs()).that(actual);
}
/**
* Asserts that the actual {@link LatLng} is within a small tolerance of the expected value.
* This is useful for accounting for floating-point inaccuracies.
*/
public void isNear(LatLng expected) {
if (Math.abs(actual.latitude - expected.latitude) > TOLERANCE ||
Math.abs(actual.longitude - expected.longitude) > TOLERANCE) {

19
ApiDemos/project/kotlin-app/src/androidTest/java/com/example/kotlindemos/truth/LatLngBoundsSubject.kt
View File

@ -6,11 +6,20 @@ import com.google.common.truth.FailureMetadata
import com.google.common.truth.Subject
import com.google.common.truth.Truth
/**
* A custom Truth subject for asserting properties of [LatLngBounds] objects.
*
* To use, static import [assertThat] and call assertions on the subject.
*/
class LatLngBoundsSubject private constructor(
failureMetadata: FailureMetadata,
private val actual: LatLngBounds
) : Subject(failureMetadata, actual) {
/**
* Asserts that the given [LatLng] is contained within the actual bounds, allowing for
* a small tolerance to account for floating-point inaccuracies.
*/
fun containsWithTolerance(expected: LatLng) {
val tolerance = 1e-5
val contains = actual.southwest.latitude - tolerance <= expected.latitude &&
@ -21,18 +30,26 @@ class LatLngBoundsSubject private constructor(
}
}
/**
* Checks if a longitude is within the bounds, correctly handling cases where the bounds
* cross the antimeridian (e.g., from 160 to -160).
*/
private fun isLongitudeWithinBounds(longitude: Double, bounds: LatLngBounds, tolerance: Double): Boolean {
return if (bounds.southwest.longitude <= bounds.northeast.longitude) {
// Standard case (e.g., from 10 to 20).
longitude >= bounds.southwest.longitude - tolerance &&
longitude <= bounds.northeast.longitude + tolerance
} else {
// The bounds cross the antimeridian.
// Case where the bounds cross the antimeridian (e.g., from 160 to -160).
longitude >= bounds.southwest.longitude - tolerance ||
longitude <= bounds.northeast.longitude + tolerance
}
}
companion object {
/**
* Creates a [LatLngBoundsSubject] for asserting on the given [LatLngBounds].
*/
fun assertThat(actual: LatLngBounds): LatLngBoundsSubject {
return Truth.assertAbout(::LatLngBoundsSubject).that(actual)
}

22
ApiDemos/project/kotlin-app/src/androidTest/java/com/example/kotlindemos/truth/LatLngSubject.kt
View File

@ -4,22 +4,40 @@ import com.google.android.gms.maps.model.LatLng
import com.google.common.truth.FailureMetadata
import com.google.common.truth.Subject
import com.google.common.truth.Truth
import kotlin.math.abs
/**
* A custom Truth subject for asserting properties of [LatLng] objects.
*
* To use, static import [assertThat] and call assertions on the subject.
* ```
* val actual = LatLng(10.0, 20.0)
* val expected = LatLng(10.000001, 20.000001)
* assertThat(actual).isNear(expected)
* ```
*/
class LatLngSubject private constructor(
failureMetadata: FailureMetadata,
private val actual: LatLng
) : Subject(failureMetadata, actual) {
/**
* Asserts that the actual [LatLng] is within a small tolerance of the expected value.
* This is useful for accounting for floating-point inaccuracies.
*/
fun isNear(expected: LatLng) {
val tolerance = 1e-6
if (Math.abs(actual.latitude - expected.latitude) > tolerance ||
Math.abs(actual.longitude - expected.longitude) > tolerance
if (abs(actual.latitude - expected.latitude) > tolerance ||
abs(actual.longitude - expected.longitude) > tolerance
) {
failWithActual("expected to be near", expected)
}
}
companion object {
/**
* Creates a [LatLngSubject] for asserting on the given [LatLng].
*/
fun assertThat(actual: LatLng): LatLngSubject {
return Truth.assertAbout(::LatLngSubject).that(actual)
}