@durable-streams/client-conformance-tests 0.1.0

package/test-cases/consumer/read-catchup.yaml

@@ -0,0 +1,173 @@
+id: consumer-catchup
+name: Catch-up Reads
+description: Tests for reading existing data from streams (catch-up mode)
+category: consumer
+tags:
+  - core
+  - read
+  - catchup
+
+tests:
+  - id: read-empty-stream
+    name: Read empty stream
+    description: Client should handle reading from an empty stream
+    setup:
+      - action: create
+        as: streamPath
+    operations:
+      - action: read
+        path: ${streamPath}
+        live: false
+        expect:
+          status: 200
+          chunkCount: 0
+          upToDate: true
+
+  - id: read-single-chunk
+    name: Read single chunk
+    description: Client should read a single chunk of data
+    setup:
+      - action: create
+        as: streamPath
+      - action: append
+        path: ${streamPath}
+        data: "Hello, World!"
+    operations:
+      - action: read
+        path: ${streamPath}
+        live: false
+        expect:
+          status: 200
+          data: "Hello, World!"
+          upToDate: true
+
+  - id: read-multiple-chunks
+    name: Read multiple chunks
+    description: Client should read all chunks concatenated
+    setup:
+      - action: create
+        as: streamPath
+      - action: append
+        path: ${streamPath}
+        data: "Chunk1 "
+      - action: append
+        path: ${streamPath}
+        data: "Chunk2 "
+      - action: append
+        path: ${streamPath}
+        data: "Chunk3"
+    operations:
+      - action: read
+        path: ${streamPath}
+        live: false
+        expect:
+          data: "Chunk1 Chunk2 Chunk3"
+          upToDate: true
+
+  - id: read-from-offset
+    name: Read from specific offset
+    description: Client should resume reading from a given offset
+    setup:
+      - action: create
+        as: streamPath
+      - action: append
+        path: ${streamPath}
+        data: "First"
+        expect:
+          storeOffsetAs: firstOffset
+      - action: append
+        path: ${streamPath}
+        data: "Second"
+    operations:
+      - action: read
+        path: ${streamPath}
+        offset: ${firstOffset}
+        live: false
+        expect:
+          data: "Second"
+          upToDate: true
+
+  - id: read-from-beginning
+    name: Read from beginning after offset
+    description: Reading without offset should start from beginning
+    setup:
+      - action: create
+        as: streamPath
+      - action: append
+        path: ${streamPath}
+        data: "Beginning"
+      - action: append
+        path: ${streamPath}
+        data: "End"
+    operations:
+      - action: read
+        path: ${streamPath}
+        live: false
+        expect:
+          data: "BeginningEnd"
+          upToDate: true
+
+  - id: read-preserves-offset
+    name: Read returns usable offset
+    description: Offset from read result can be used to resume
+    setup:
+      - action: create
+        as: streamPath
+      - action: append
+        path: ${streamPath}
+        data: "Part1"
+      - action: append
+        path: ${streamPath}
+        data: "Part2"
+    operations:
+      - action: read
+        path: ${streamPath}
+        maxChunks: 1
+        live: false
+        expect:
+          storeOffsetAs: resumeOffset
+      - action: append
+        path: ${streamPath}
+        data: "Part3"
+      - action: read
+        path: ${streamPath}
+        offset: ${resumeOffset}
+        live: false
+        expect:
+          dataContains: "Part3"
+
+  - id: read-binary-data
+    name: Read binary data
+    description: Client should correctly read binary data
+    setup:
+      - action: create
+        as: streamPath
+        contentType: application/octet-stream
+      - action: append
+        path: ${streamPath}
+        binaryData: "AQID" # [1, 2, 3] in base64
+    operations:
+      - action: read
+        path: ${streamPath}
+        live: false
+        expect:
+          status: 200
+          upToDate: true
+
+  - id: read-unicode-data
+    name: Read unicode data
+    description: Client should correctly handle unicode in reads
+    setup:
+      - action: create
+        as: streamPath
+        contentType: text/plain; charset=utf-8
+      - action: append
+        path: ${streamPath}
+        data: "Unicode: 日本語 🎉 Ñoño"
+    operations:
+      - action: read
+        path: ${streamPath}
+        live: false
+        expect:
+          data: "Unicode: 日本語 🎉 Ñoño"
+          upToDate: true

package/test-cases/consumer/read-longpoll.yaml

@@ -0,0 +1,132 @@
+id: consumer-longpoll
+name: Long-Poll Reads
+description: Tests for long-poll live reading from streams
+category: consumer
+tags:
+  - core
+  - read
+  - longpoll
+  - live
+requires:
+  - long-poll
+
+tests:
+  - id: longpoll-waits-for-data
+    name: Long-poll waits for new data
+    description: Client should wait for new data in long-poll mode
+    setup:
+      - action: create
+        as: streamPath
+      - action: append
+        path: ${streamPath}
+        data: "initial"
+        expect:
+          storeOffsetAs: initialOffset
+    operations:
+      # Start long-poll read in background (will be waiting for new data)
+      - action: read
+        path: ${streamPath}
+        offset: ${initialOffset}
+        live: long-poll
+        timeoutMs: 10000
+        background: true
+        as: readOp
+      # Wait for the read to start
+      - action: wait
+        ms: 200
+      # Append data via direct server HTTP (adapter is blocked on read)
+      - action: server-append
+        path: ${streamPath}
+        data: "new-data"
+      # Wait for the background read to complete
+      - action: await
+        ref: readOp
+        expect:
+          dataContains: "new-data"
+
+  - id: longpoll-returns-immediately-with-data
+    name: Long-poll returns immediately if data exists
+    description: Long-poll should not wait if there's already data to return
+    setup:
+      - action: create
+        as: streamPath
+      - action: append
+        path: ${streamPath}
+        data: "existing-data"
+    operations:
+      - action: read
+        path: ${streamPath}
+        live: long-poll
+        timeoutMs: 1000
+        expect:
+          data: "existing-data"
+          upToDate: true
+
+  - id: longpoll-timeout
+    name: Long-poll times out gracefully
+    description: Long-poll should timeout and return up-to-date when no new data arrives
+    setup:
+      - action: create
+        as: streamPath
+      - action: append
+        path: ${streamPath}
+        data: "initial"
+        expect:
+          storeOffsetAs: offset
+    operations:
+      - action: read
+        path: ${streamPath}
+        offset: ${offset}
+        live: long-poll
+        timeoutMs: 500
+        expect:
+          chunkCount: 0
+          upToDate: true
+
+  - id: longpoll-multiple-chunks
+    name: Long-poll receives multiple chunks
+    description: Long-poll should receive all available chunks
+    setup:
+      - action: create
+        as: streamPath
+    operations:
+      - action: append
+        path: ${streamPath}
+        data: "chunk1"
+      - action: append
+        path: ${streamPath}
+        data: "chunk2"
+      - action: append
+        path: ${streamPath}
+        data: "chunk3"
+      - action: read
+        path: ${streamPath}
+        live: long-poll
+        timeoutMs: 1000
+        expect:
+          data: "chunk1chunk2chunk3"
+          upToDate: true
+
+  - id: longpoll-resume-from-offset
+    name: Long-poll resumes from offset
+    description: Long-poll should resume from the provided offset
+    setup:
+      - action: create
+        as: streamPath
+      - action: append
+        path: ${streamPath}
+        data: "old-data"
+        expect:
+          storeOffsetAs: offset
+      - action: append
+        path: ${streamPath}
+        data: "new-data"
+    operations:
+      - action: read
+        path: ${streamPath}
+        offset: ${offset}
+        live: long-poll
+        timeoutMs: 1000
+        expect:
+          data: "new-data"
+          upToDate: true

package/test-cases/consumer/read-sse.yaml

@@ -0,0 +1,145 @@
+id: consumer-sse
+name: SSE Reads
+description: Tests for Server-Sent Events live reading from streams
+category: consumer
+tags:
+  - core
+  - read
+  - sse
+  - live
+requires:
+  - sse
+
+tests:
+  - id: sse-receives-existing-data
+    name: SSE receives existing data
+    description: SSE stream should first deliver existing data
+    setup:
+      - action: create
+        as: streamPath
+      - action: append
+        path: ${streamPath}
+        data: "existing1"
+      - action: append
+        path: ${streamPath}
+        data: "existing2"
+    operations:
+      - action: read
+        path: ${streamPath}
+        live: sse
+        maxChunks: 2
+        waitForUpToDate: true
+        expect:
+          dataContainsAll:
+            - "existing1"
+            - "existing2"
+          minChunks: 1
+
+  - id: sse-receives-new-data
+    name: SSE receives new data
+    description: SSE stream should receive data appended after connection
+    setup:
+      - action: create
+        as: streamPath
+      - action: append
+        path: ${streamPath}
+        data: "initial"
+        expect:
+          storeOffsetAs: offset
+    operations:
+      # Start SSE read in background (will be waiting for new data)
+      - action: read
+        path: ${streamPath}
+        offset: ${offset}
+        live: sse
+        maxChunks: 1
+        timeoutMs: 10000
+        background: true
+        as: readOp
+      # Wait for the SSE connection to establish
+      - action: wait
+        ms: 200
+      # Append data via direct server HTTP (adapter is blocked on read)
+      - action: server-append
+        path: ${streamPath}
+        data: "new-data"
+      # Wait for the background read to complete
+      - action: await
+        ref: readOp
+        expect:
+          dataContains: "new-data"
+          minChunks: 1
+
+  - id: sse-resumes-from-offset
+    name: SSE resumes from offset
+    description: SSE should start from specified offset
+    setup:
+      - action: create
+        as: streamPath
+      - action: append
+        path: ${streamPath}
+        data: "skip-this"
+        expect:
+          storeOffsetAs: skipOffset
+      - action: append
+        path: ${streamPath}
+        data: "include-this"
+    operations:
+      - action: read
+        path: ${streamPath}
+        offset: ${skipOffset}
+        live: sse
+        waitForUpToDate: true
+        expect:
+          data: "include-this"
+
+  - id: sse-up-to-date-signal
+    name: SSE signals up-to-date
+    description: SSE should indicate when caught up to head
+    setup:
+      - action: create
+        as: streamPath
+      - action: append
+        path: ${streamPath}
+        data: "data"
+    operations:
+      - action: read
+        path: ${streamPath}
+        live: sse
+        waitForUpToDate: true
+        expect:
+          upToDate: true
+
+  - id: sse-empty-stream
+    name: SSE on empty stream
+    description: SSE should work on empty stream and signal up-to-date
+    setup:
+      - action: create
+        as: streamPath
+    operations:
+      - action: read
+        path: ${streamPath}
+        live: sse
+        waitForUpToDate: true
+        expect:
+          upToDate: true
+          chunkCount: 0
+
+  - id: sse-binary-data
+    name: SSE with binary data
+    description: SSE should correctly transmit binary data
+    setup:
+      - action: create
+        as: streamPath
+        contentType: application/octet-stream
+      - action: append
+        path: ${streamPath}
+        binaryData: "/f7/AA==" # some binary bytes
+    operations:
+      - action: read
+        path: ${streamPath}
+        live: sse
+        waitForUpToDate: true
+        expect:
+          minChunks: 1
+          upToDate: true

package/test-cases/consumer/retry-resilience.yaml

@@ -0,0 +1,160 @@
+id: consumer-retry-resilience
+name: Retry and Resilience
+description: Tests for client retry behavior on transient errors
+category: consumer
+tags:
+  - core
+  - retry
+  - resilience
+  - error-handling
+
+tests:
+  - id: retry-on-500
+    name: Client retries on 500 Internal Server Error
+    description: Client should automatically retry when server returns 500
+    setup:
+      - action: create
+        as: streamPath
+      - action: append
+        path: ${streamPath}
+        data: "test-data"
+    operations:
+      # Inject a 500 error for the first request
+      - action: inject-error
+        path: ${streamPath}
+        status: 500
+        count: 1
+      # Client should retry and eventually succeed
+      - action: read
+        path: ${streamPath}
+        expect:
+          data: "test-data"
+    cleanup:
+      - action: clear-errors
+
+  - id: retry-on-503
+    name: Client retries on 503 Service Unavailable
+    description: Client should automatically retry when server returns 503
+    setup:
+      - action: create
+        as: streamPath
+      - action: append
+        path: ${streamPath}
+        data: "test-data"
+    operations:
+      # Inject a 503 error for the first request
+      - action: inject-error
+        path: ${streamPath}
+        status: 503
+        count: 1
+      # Client should retry and eventually succeed
+      - action: read
+        path: ${streamPath}
+        expect:
+          data: "test-data"
+    cleanup:
+      - action: clear-errors
+
+  - id: retry-on-429
+    name: Client retries on 429 Too Many Requests
+    description: Client should retry after rate limiting with backoff
+    setup:
+      - action: create
+        as: streamPath
+      - action: append
+        path: ${streamPath}
+        data: "test-data"
+    operations:
+      # Inject a 429 error with Retry-After header
+      - action: inject-error
+        path: ${streamPath}
+        status: 429
+        count: 1
+        retryAfter: 1
+      # Client should wait and retry, eventually succeeding
+      - action: read
+        path: ${streamPath}
+        expect:
+          data: "test-data"
+    cleanup:
+      - action: clear-errors
+
+  - id: retry-multiple-failures
+    name: Client retries through multiple transient failures
+    description: Client should retry through several consecutive 500 errors
+    setup:
+      - action: create
+        as: streamPath
+      - action: append
+        path: ${streamPath}
+        data: "persisted-data"
+    operations:
+      # Inject 2 consecutive 500 errors
+      - action: inject-error
+        path: ${streamPath}
+        status: 500
+        count: 2
+      # Client should retry multiple times and eventually succeed
+      - action: read
+        path: ${streamPath}
+        expect:
+          data: "persisted-data"
+    cleanup:
+      - action: clear-errors
+
+  - id: no-retry-on-404
+    name: Client does not retry on 404 Not Found
+    description: 404 is a permanent error and should not be retried
+    operations:
+      # Try to read from non-existent stream (will get 404)
+      - action: read
+        path: /non-existent-stream-${randomUUID}
+        expect:
+          status: 404
+
+  - id: no-retry-on-400
+    name: Client does not retry on 400 Bad Request
+    description: 400 is a client error and should not be retried
+    setup:
+      - action: create
+        as: streamPath
+      - action: append
+        path: ${streamPath}
+        data: "data"
+    operations:
+      # Inject a 400 error
+      - action: inject-error
+        path: ${streamPath}
+        status: 400
+        count: 1
+      # Client should not retry, should fail immediately
+      - action: read
+        path: ${streamPath}
+        expect:
+          status: 400
+    cleanup:
+      - action: clear-errors
+
+  - id: append-retry-on-500
+    name: Append retries on 500 Internal Server Error
+    description: Append should automatically retry when server returns 500
+    setup:
+      - action: create
+        as: streamPath
+    operations:
+      # Inject a 500 error for the first append
+      - action: inject-error
+        path: ${streamPath}
+        status: 500
+        count: 1
+      # Client should retry and eventually succeed
+      - action: append
+        path: ${streamPath}
+        data: "retry-data"
+      # Verify data was appended
+      - action: read
+        path: ${streamPath}
+        expect:
+          data: "retry-data"
+    cleanup:
+      - action: clear-errors