MV-GH · Oct 19, 2026 · Oct 19, 2026 · Oct 19, 2026 · Oct 19, 2026 · Oct 19, 2026
diff --git a/.github/workflows/e2e.yml b/.github/workflows/e2e.yml
@@ -0,0 +1,31 @@
+name: E2E
+
+# Manual only: run from the Actions tab ("Run workflow") or `gh workflow run e2e.yml`
+on:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  e2e:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-java@v5
+        with:
+          distribution: 'temurin'
+          java-version: '17'
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v5
+      - run: ./gradlew :app:e2eTest
+      - name: Upload test reports
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: e2e-test-reports
+          path: app/build/reports/tests/e2eTest
+          if-no-files-found: ignore
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -39,6 +39,11 @@ The `it.vercruysse.lemmyapi.datatypes` package represents the **1.0.0 Lemmy API*
 - **Enum entries**: each entry tracks `minimumVersion`/`maximumVersion`. Use `getSupportedEntries<Type>()` to retrieve the valid entries for the connected instance (e.g. sort options).
 
 
+## End-to-end tests
+
+`gradlew :app:e2eTest` runs the library against a real Lemmy server (currently v1 only) started with Testcontainers, so a running Docker engine is required.
+
+
 ## Compatibility Rules
 
 When adding or updating an older-version implementation:

diff --git a/GeneratorScripts/src/main/kotlin/autogenscripts/GenTypes.kt b/GeneratorScripts/src/main/kotlin/autogenscripts/GenTypes.kt
@@ -78,13 +78,15 @@ val fileFieldEnumOverrides = mapOf(
 // Maps the interface name to its @JsonClassDiscriminator field, and whether it needs @Serializable.
 data class SealedInterface(val discriminator: String, val serializable: Boolean = false)
 
-// TODO: don't know yet if serializable required but also it breaks the generated code
+// Interfaces that are deserialized polymorphically (as response fields) must be @Serializable,
+// otherwise the class discriminator is not resolved at runtime.
+// TODO refactor
 val sealedInterfaces = mapOf(
-    "PostOrCommentOrPrivateMessage" to SealedInterface("type_"),
-    "ResolveObjectView"            to SealedInterface("type_"),
-    "ReportCombinedView"            to SealedInterface("type_"),
-    "NotificationData"              to SealedInterface("type_", serializable = false),
-    "PostCommentCombinedView"       to SealedInterface("type_"),
+    "PostOrCommentOrPrivateMessage" to SealedInterface("type_", serializable = true),
+    "ResolveObjectView"            to SealedInterface("type_", serializable = true),
+    "ReportCombinedView"            to SealedInterface("type_", serializable = true),
+    "NotificationData"              to SealedInterface("type_", serializable = true),
+    "PostCommentCombinedView"       to SealedInterface("type_", serializable = true),
 )
 
 // Which data classes implement which sealed interfaces and what @SerialName they carry.

diff --git a/app/build.gradle.kts b/app/build.gradle.kts
@@ -25,6 +25,12 @@ kotlin {
                 useJUnitPlatform()
             }
         }
+
+        // Separate compilation so the Docker-based E2E tests never run as part of `jvmTest`/`check`
+        val mainCompilation = compilations.getByName("main")
+        compilations.create("e2eTest") {
+            associateWith(mainCompilation)
+        }
     }
 
     android {
@@ -92,6 +98,13 @@ kotlin {
             implementation("io.ktor:ktor-client-mock:$ktorVersion")
         }
 
+        getByName("jvmE2eTest").dependencies {
+            implementation(kotlin("test-junit5"))
+            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.11.0")
+            implementation("org.testcontainers:testcontainers:1.21.4")
+            implementation("ch.qos.logback:logback-classic:1.6.3")
+        }
+
         // Below required bc we use HttpClient() see https://ktor.io/docs/client-engines.html#default
 
         jsMain.dependencies {
@@ -129,6 +142,21 @@ kotlin {
 }
 
 
+val e2eCompilation = kotlin.jvm().compilations.getByName("e2eTest")
+
+tasks.register<Test>("e2eTest") {
+    description = "Runs JVM E2E tests against a local Lemmy docker setup."
+    group = "verification"
+    testClassesDirs = e2eCompilation.output.classesDirs
+    classpath = files(e2eCompilation.output.allOutputs, e2eCompilation.runtimeDependencyFiles)
+    useJUnitPlatform()
+    outputs.upToDateWhen { false }
+    testLogging {
+        events("passed", "failed", "skipped")
+        showStandardStreams = true
+    }
+}
+
 tasks.withType<LintTask> {
     exclude("**/datatypes/**")
 }

diff --git a/app/src/commonMain/kotlin/it/vercruysse/lemmyapi/utils/Ktor.kt b/app/src/commonMain/kotlin/it/vercruysse/lemmyapi/utils/Ktor.kt
@@ -56,7 +56,7 @@ suspend inline fun <reified R> HttpClient.postUploadResult(
             MultiPartFormDataContent(
                 formData {
                     append(
-                        "image", // TODO: this might need to be images[]
+                        "images[]",
                         image,
                         Headers.build {
                             append(HttpHeaders.ContentDisposition, "filename=\"image.jpg\"")

diff --git a/app/src/commonMain/kotlin/it/vercruysse/lemmyapi/v1/x0/x0/LemmyApiUniWrapper.kt b/app/src/commonMain/kotlin/it/vercruysse/lemmyapi/v1/x0/x0/LemmyApiUniWrapper.kt
@@ -32,7 +32,7 @@ internal class LemmyApiUniWrapper(client: HttpClient, apiBaseUrl: String, instan
 
     override suspend fun getModlog(form: it.vercruysse.lemmyapi.datatypes.GetModlog): Result<PagedResponse<it.vercruysse.lemmyapi.datatypes.ModlogView>> =
         api.getModlog(transformer.fromUni(form)).map { resp ->
-            PagedResponse(resp.items.map(transformer::toUni))
+            PagedResponse(resp.items.map(transformer::toUni), resp.next_page, resp.prev_page)
         }
 
     override suspend fun search(form: it.vercruysse.lemmyapi.datatypes.Search): Result<it.vercruysse.lemmyapi.datatypes.SearchResponse> =
@@ -55,7 +55,7 @@ internal class LemmyApiUniWrapper(client: HttpClient, apiBaseUrl: String, instan
 
     override suspend fun listCommunities(form: it.vercruysse.lemmyapi.datatypes.ListCommunities): Result<PagedResponse<it.vercruysse.lemmyapi.datatypes.CommunityView>> =
         api.listCommunities(transformer.fromUni(form)).map { resp ->
-            PagedResponse(resp.items.map(transformer::toUni))
+            PagedResponse(resp.items.map(transformer::toUni), resp.next_page, resp.prev_page)
         }
 
     override suspend fun followCommunity(form: it.vercruysse.lemmyapi.datatypes.FollowCommunity): Result<it.vercruysse.lemmyapi.datatypes.CommunityResponse> =
@@ -81,7 +81,7 @@ internal class LemmyApiUniWrapper(client: HttpClient, apiBaseUrl: String, instan
 
     override suspend fun getFederatedInstances(form: it.vercruysse.lemmyapi.datatypes.GetFederatedInstances): Result<PagedResponse<it.vercruysse.lemmyapi.datatypes.FederatedInstanceView>> =
         api.getFederatedInstances(transformer.fromUni(form)).map { resp ->
-            PagedResponse(resp.items.map(transformer::toUni))
+            PagedResponse(resp.items.map(transformer::toUni), resp.next_page, resp.prev_page)
         }
 
     override suspend fun getPost(form: it.vercruysse.lemmyapi.datatypes.GetPost): Result<it.vercruysse.lemmyapi.datatypes.GetPostResponse> =
@@ -95,7 +95,7 @@ internal class LemmyApiUniWrapper(client: HttpClient, apiBaseUrl: String, instan
 
     override suspend fun getPosts(form: it.vercruysse.lemmyapi.datatypes.GetPosts): Result<PagedResponse<it.vercruysse.lemmyapi.datatypes.PostView>> =
         api.getPosts(transformer.fromUni(form.toValidatedForm())).map { resp ->
-            PagedResponse(resp.items.map(transformer::toUni))
+            PagedResponse(resp.items.map(transformer::toUni), resp.next_page, resp.prev_page)
         }
 
     override suspend fun deletePost(form: it.vercruysse.lemmyapi.datatypes.DeletePost): Result<it.vercruysse.lemmyapi.datatypes.PostResponse> =
@@ -130,7 +130,7 @@ internal class LemmyApiUniWrapper(client: HttpClient, apiBaseUrl: String, instan
 
     override suspend fun listReports(form: it.vercruysse.lemmyapi.datatypes.ListReports): Result<PagedResponse<it.vercruysse.lemmyapi.datatypes.ReportCombinedView>> =
         api.listReports(transformer.fromUni(form)).map { resp ->
-            PagedResponse(resp.items.map(transformer::toUni))
+            PagedResponse(resp.items.map(transformer::toUni), resp.next_page, resp.prev_page)
         }
 
     override suspend fun getSiteMetadata(form: it.vercruysse.lemmyapi.datatypes.GetSiteMetadata): Result<it.vercruysse.lemmyapi.datatypes.GetSiteMetadataResponse> =
@@ -147,7 +147,7 @@ internal class LemmyApiUniWrapper(client: HttpClient, apiBaseUrl: String, instan
 
     override suspend fun getComments(form: it.vercruysse.lemmyapi.datatypes.GetComments): Result<PagedResponse<it.vercruysse.lemmyapi.datatypes.CommentView>> =
         api.getComments(transformer.fromUni(form)).map { resp ->
-            PagedResponse(resp.items.map(transformer::toUni))
+            PagedResponse(resp.items.map(transformer::toUni), resp.next_page, resp.prev_page)
         }
 
     override suspend fun deleteComment(form: it.vercruysse.lemmyapi.datatypes.DeleteComment): Result<it.vercruysse.lemmyapi.datatypes.CommentResponse> =
@@ -191,7 +191,7 @@ internal class LemmyApiUniWrapper(client: HttpClient, apiBaseUrl: String, instan
 
     override suspend fun listPersons(form: it.vercruysse.lemmyapi.datatypes.ListPersons): Result<PagedResponse<it.vercruysse.lemmyapi.datatypes.PersonView>> =
         api.listPersons(transformer.fromUni(form)).map { resp ->
-            PagedResponse(resp.items.map(transformer::toUni))
+            PagedResponse(resp.items.map(transformer::toUni), resp.next_page, resp.prev_page)
         }
 
     override suspend fun register(form: it.vercruysse.lemmyapi.datatypes.Register): Result<it.vercruysse.lemmyapi.datatypes.LoginResponse> =
@@ -208,7 +208,7 @@ internal class LemmyApiUniWrapper(client: HttpClient, apiBaseUrl: String, instan
 
     override suspend fun listNotifications(form: ListNotifications): Result<PagedResponse<it.vercruysse.lemmyapi.datatypes.NotificationView>> =
         api.listNotifications(transformer.fromUni(form)).map { resp ->
-            PagedResponse(resp.items.map(transformer::toUni))
+            PagedResponse(resp.items.map(transformer::toUni), resp.next_page, resp.prev_page)
         }
 
     override suspend fun banPerson(form: it.vercruysse.lemmyapi.datatypes.BanPerson): Result<it.vercruysse.lemmyapi.datatypes.PersonResponse> =
@@ -255,7 +255,7 @@ internal class LemmyApiUniWrapper(client: HttpClient, apiBaseUrl: String, instan
 
     override suspend fun listRegistrationApplications(form: it.vercruysse.lemmyapi.datatypes.ListRegistrationApplications): Result<PagedResponse<it.vercruysse.lemmyapi.datatypes.RegistrationApplicationView>> =
         api.listRegistrationApplications(transformer.fromUni(form)).map { resp ->
-            PagedResponse(resp.items.map(transformer::toUni))
+            PagedResponse(resp.items.map(transformer::toUni), resp.next_page, resp.prev_page)
         }
 
     override suspend fun approveRegistrationApplication(form: it.vercruysse.lemmyapi.datatypes.ApproveRegistrationApplication): Result<it.vercruysse.lemmyapi.datatypes.RegistrationApplicationResponse> =
@@ -314,12 +314,12 @@ internal class LemmyApiUniWrapper(client: HttpClient, apiBaseUrl: String, instan
 
     override suspend fun listPostLikes(form: it.vercruysse.lemmyapi.datatypes.ListPostLikes): Result<PagedResponse<it.vercruysse.lemmyapi.datatypes.VoteView>> =
         api.listPostLikes(transformer.fromUni(form)).map { resp ->
-            PagedResponse(resp.items.map(transformer::toUni))
+            PagedResponse(resp.items.map(transformer::toUni), resp.next_page, resp.prev_page)
         }
 
     override suspend fun listCommentLikes(form: it.vercruysse.lemmyapi.datatypes.ListCommentLikes): Result<PagedResponse<it.vercruysse.lemmyapi.datatypes.VoteView>> =
         api.listCommentLikes(transformer.fromUni(form)).map { resp ->
-            PagedResponse(resp.items.map(transformer::toUni))
+            PagedResponse(resp.items.map(transformer::toUni), resp.next_page, resp.prev_page)
         }
 
     override suspend fun createRegistrationInvitation(form: it.vercruysse.lemmyapi.datatypes.CreateInvitation): Result<it.vercruysse.lemmyapi.datatypes.CreateInvitationResponse> =
@@ -330,17 +330,17 @@ internal class LemmyApiUniWrapper(client: HttpClient, apiBaseUrl: String, instan
 
     override suspend fun listRegistrationInvitations(form: it.vercruysse.lemmyapi.datatypes.ListInvitations): Result<PagedResponse<it.vercruysse.lemmyapi.datatypes.LocalUserInvite>> =
         api.listRegistrationInvitations(transformer.fromUni(form)).map { resp ->
-            PagedResponse(resp.items.map(transformer::toUni))
+            PagedResponse(resp.items.map(transformer::toUni), resp.next_page, resp.prev_page)
         }
 
     override suspend fun listMedia(form: it.vercruysse.lemmyapi.datatypes.ListMedia): Result<PagedResponse<it.vercruysse.lemmyapi.datatypes.LocalImageView>> =
         api.listMedia(transformer.fromUni(form)).map { resp ->
-            PagedResponse(resp.items.map(transformer::toUni))
+            PagedResponse(resp.items.map(transformer::toUni), resp.next_page, resp.prev_page)
         }
 
     override suspend fun listMediaAdmin(form: it.vercruysse.lemmyapi.datatypes.ListMedia): Result<PagedResponse<it.vercruysse.lemmyapi.datatypes.LocalImageView>> =
         api.listMediaAdmin(transformer.fromUni(form)).map { resp ->
-            PagedResponse(resp.items.map(transformer::toUni))
+            PagedResponse(resp.items.map(transformer::toUni), resp.next_page, resp.prev_page)
         }
 
     override suspend fun hidePost(form: it.vercruysse.lemmyapi.datatypes.HidePost): Result<it.vercruysse.lemmyapi.datatypes.PostResponse> =
@@ -353,7 +353,7 @@ internal class LemmyApiUniWrapper(client: HttpClient, apiBaseUrl: String, instan
 
     override suspend fun listPersonContent(form: it.vercruysse.lemmyapi.datatypes.ListPersonContent): Result<PagedResponse<it.vercruysse.lemmyapi.datatypes.PostCommentCombinedView>> =
         api.listPersonContent(transformer.fromUni(form)).map { resp ->
-            PagedResponse(resp.items.map(transformer::toUni))
+            PagedResponse(resp.items.map(transformer::toUni), resp.next_page, resp.prev_page)
         }
 
     override suspend fun uploadImage(image: ByteArray): Result<it.vercruysse.lemmyapi.datatypes.UploadImageResponse> =
@@ -406,7 +406,7 @@ internal class LemmyApiUniWrapper(client: HttpClient, apiBaseUrl: String, instan
 
     override suspend fun adminListUsers(form: it.vercruysse.lemmyapi.datatypes.AdminListUsers): Result<PagedResponse<it.vercruysse.lemmyapi.datatypes.LocalUserView>> =
         api.adminListUsers(transformer.fromUni(form)).map { resp ->
-            PagedResponse(resp.items.map(transformer::toUni))
+            PagedResponse(resp.items.map(transformer::toUni), resp.next_page, resp.prev_page)
         }
 
     override suspend fun getRandomCommunity(form: it.vercruysse.lemmyapi.datatypes.GetRandomCommunity): Result<it.vercruysse.lemmyapi.datatypes.CommunityResponse> =
@@ -435,7 +435,7 @@ internal class LemmyApiUniWrapper(client: HttpClient, apiBaseUrl: String, instan
 
     override suspend fun listCommunityPendingFollows(form: it.vercruysse.lemmyapi.datatypes.ListCommunityPendingFollows): Result<PagedResponse<it.vercruysse.lemmyapi.datatypes.PendingFollowerView>> =
         api.listCommunityPendingFollows(transformer.fromUni(form)).map { resp ->
-            PagedResponse(resp.items.map(transformer::toUni))
+            PagedResponse(resp.items.map(transformer::toUni), resp.next_page, resp.prev_page)
         }
 
     override suspend fun modEditPost(form: it.vercruysse.lemmyapi.datatypes.ModEditPost): Result<it.vercruysse.lemmyapi.datatypes.PostResponse> =
@@ -449,7 +449,7 @@ internal class LemmyApiUniWrapper(client: HttpClient, apiBaseUrl: String, instan
 
     override suspend fun getCommentsSlim(form: it.vercruysse.lemmyapi.datatypes.GetComments): Result<PagedResponse<it.vercruysse.lemmyapi.datatypes.CommentSlimView>> =
         api.getCommentsSlim(transformer.fromUni(form)).map { resp ->
-            PagedResponse(resp.items.map(transformer::toUni))
+            PagedResponse(resp.items.map(transformer::toUni), resp.next_page, resp.prev_page)
         }
 
     override suspend fun lockComment(form: it.vercruysse.lemmyapi.datatypes.LockComment): Result<it.vercruysse.lemmyapi.datatypes.CommentResponse> =
@@ -463,22 +463,22 @@ internal class LemmyApiUniWrapper(client: HttpClient, apiBaseUrl: String, instan
 
     override suspend fun listPersonSaved(form: it.vercruysse.lemmyapi.datatypes.ListPersonSaved): Result<PagedResponse<it.vercruysse.lemmyapi.datatypes.PostCommentCombinedView>> =
         api.listPersonSaved(transformer.fromUni(form)).map { resp ->
-            PagedResponse(resp.items.map(transformer::toUni))
+            PagedResponse(resp.items.map(transformer::toUni), resp.next_page, resp.prev_page)
         }
 
     override suspend fun listPersonRead(form: it.vercruysse.lemmyapi.datatypes.ListPersonRead): Result<PagedResponse<it.vercruysse.lemmyapi.datatypes.PostView>> =
         api.listPersonRead(transformer.fromUni(form)).map { resp ->
-            PagedResponse(resp.items.map(transformer::toUni))
+            PagedResponse(resp.items.map(transformer::toUni), resp.next_page, resp.prev_page)
         }
 
     override suspend fun listPersonHidden(form: it.vercruysse.lemmyapi.datatypes.ListPersonHidden): Result<PagedResponse<it.vercruysse.lemmyapi.datatypes.PostView>> =
         api.listPersonHidden(transformer.fromUni(form)).map { resp ->
-            PagedResponse(resp.items.map(transformer::toUni))
+            PagedResponse(resp.items.map(transformer::toUni), resp.next_page, resp.prev_page)
         }
 
     override suspend fun listPersonLiked(form: it.vercruysse.lemmyapi.datatypes.ListPersonLiked): Result<PagedResponse<it.vercruysse.lemmyapi.datatypes.PostCommentCombinedView>> =
         api.listPersonLiked(transformer.fromUni(form)).map { resp ->
-            PagedResponse(resp.items.map(transformer::toUni))
+            PagedResponse(resp.items.map(transformer::toUni), resp.next_page, resp.prev_page)
         }
 
     override suspend fun resendVerificationEmail(form: it.vercruysse.lemmyapi.datatypes.ResendVerificationEmail): Result<Unit> =
@@ -507,7 +507,7 @@ internal class LemmyApiUniWrapper(client: HttpClient, apiBaseUrl: String, instan
 
     override suspend fun listTaglines(form: it.vercruysse.lemmyapi.datatypes.ListTaglines): Result<PagedResponse<it.vercruysse.lemmyapi.datatypes.Tagline>> =
         api.listTaglines(transformer.fromUni(form)).map { resp ->
-            PagedResponse(resp.items.map(transformer::toUni))
+            PagedResponse(resp.items.map(transformer::toUni), resp.next_page, resp.prev_page)
         }
 
     override suspend fun createOAuthProvider(form: it.vercruysse.lemmyapi.datatypes.CreateOAuthProvider): Result<it.vercruysse.lemmyapi.datatypes.AdminOAuthProvider> =
@@ -539,6 +539,6 @@ internal class LemmyApiUniWrapper(client: HttpClient, apiBaseUrl: String, instan
 
     override suspend fun listMultiCommunities(form: it.vercruysse.lemmyapi.datatypes.ListMultiCommunities): Result<PagedResponse<it.vercruysse.lemmyapi.datatypes.MultiCommunityView>> =
         api.listMultiCommunities(transformer.fromUni(form)).map { resp ->
-            PagedResponse(resp.items.map(transformer::toUni))
+            PagedResponse(resp.items.map(transformer::toUni), resp.next_page, resp.prev_page)
         }
 }
diff --git a/app/src/commonMain/kotlin/it/vercruysse/lemmyapi/v1/x0/x0/datatypes/NotificationData.kt b/app/src/commonMain/kotlin/it/vercruysse/lemmyapi/v1/x0/x0/datatypes/NotificationData.kt
@@ -1,8 +1,10 @@
 package it.vercruysse.lemmyapi.v1.x0.x0.datatypes
 
 import kotlinx.serialization.ExperimentalSerializationApi
+import kotlinx.serialization.Serializable
 import kotlinx.serialization.json.JsonClassDiscriminator
 
 @OptIn(ExperimentalSerializationApi::class)
+@Serializable
 @JsonClassDiscriminator("type_")
 internal sealed interface NotificationData
diff --git a/...rc/commonMain/kotlin/it/vercruysse/lemmyapi/v1/x0/x0/datatypes/PostCommentCombinedView.kt b/...rc/commonMain/kotlin/it/vercruysse/lemmyapi/v1/x0/x0/datatypes/PostCommentCombinedView.kt
@@ -1,8 +1,10 @@
 package it.vercruysse.lemmyapi.v1.x0.x0.datatypes
 
 import kotlinx.serialization.ExperimentalSerializationApi
+import kotlinx.serialization.Serializable
 import kotlinx.serialization.json.JsonClassDiscriminator
 
 @OptIn(ExperimentalSerializationApi::class)
+@Serializable
 @JsonClassDiscriminator("type_")
 internal sealed interface PostCommentCombinedView
diff --git a/...monMain/kotlin/it/vercruysse/lemmyapi/v1/x0/x0/datatypes/PostOrCommentOrPrivateMessage.kt b/...monMain/kotlin/it/vercruysse/lemmyapi/v1/x0/x0/datatypes/PostOrCommentOrPrivateMessage.kt
@@ -1,8 +1,10 @@
 package it.vercruysse.lemmyapi.v1.x0.x0.datatypes
 
 import kotlinx.serialization.ExperimentalSerializationApi
+import kotlinx.serialization.Serializable
 import kotlinx.serialization.json.JsonClassDiscriminator
 
 @OptIn(ExperimentalSerializationApi::class)
+@Serializable
 @JsonClassDiscriminator("type_")
 internal sealed interface PostOrCommentOrPrivateMessage