From d1bb0713097b8af663ecfecb5474042c81c77262 Mon Sep 17 00:00:00 2001 From: Roman Elizarov Date: Tue, 22 Sep 2020 11:16:38 +0300 Subject: [PATCH] Update Flow.sample KDoc example timings, add tests * All Flow.debounce/sample KDoc example code snippets are automatically tested with Knit. * Flow.sample timings are made larger, so that they produce an expected output when run under the real time, too. Fixes #2243 --- docs/knit.properties | 12 ---- docs/knit.test.template | 1 + gradle.properties | 2 +- knit.properties | 16 +++++ .../common/src/flow/operators/Delay.kt | 72 +++++++++++++++---- .../jvm/test/examples/example-delay-01.kt | 24 +++++++ .../jvm/test/examples/example-delay-02.kt | 19 +++++ .../examples/example-delay-duration-01.kt | 26 +++++++ .../examples/example-delay-duration-02.kt | 21 ++++++ .../jvm/test/examples/test/FlowDelayTest.kt | 39 ++++++++++ .../jvm/test/guide/test/BasicsGuideTest.kt | 1 + .../test/guide/test/CancellationGuideTest.kt | 1 + .../jvm/test/guide/test/ChannelsGuideTest.kt | 1 + .../jvm/test/guide/test/ComposingGuideTest.kt | 1 + .../test/guide/test/DispatcherGuideTest.kt | 1 + .../test/guide/test/ExceptionsGuideTest.kt | 1 + .../jvm/test/guide/test/FlowGuideTest.kt | 1 + .../jvm/test/guide/test/SelectGuideTest.kt | 1 + .../test/guide/test/SharedStateGuideTest.kt | 1 + .../jvm/test/{guide/test => knit}/TestUtil.kt | 4 +- kotlinx-coroutines-core/knit.properties | 10 +++ 21 files changed, 228 insertions(+), 27 deletions(-) create mode 100644 knit.properties create mode 100644 kotlinx-coroutines-core/jvm/test/examples/example-delay-01.kt create mode 100644 kotlinx-coroutines-core/jvm/test/examples/example-delay-02.kt create mode 100644 kotlinx-coroutines-core/jvm/test/examples/example-delay-duration-01.kt create mode 100644 kotlinx-coroutines-core/jvm/test/examples/example-delay-duration-02.kt create mode 100644 kotlinx-coroutines-core/jvm/test/examples/test/FlowDelayTest.kt rename kotlinx-coroutines-core/jvm/test/{guide/test => knit}/TestUtil.kt (98%) create mode 100644 kotlinx-coroutines-core/knit.properties diff --git a/docs/knit.properties b/docs/knit.properties index ab2508a114..2028ecb416 100644 --- a/docs/knit.properties +++ b/docs/knit.properties @@ -4,19 +4,7 @@ knit.package=kotlinx.coroutines.guide knit.dir=../kotlinx-coroutines-core/jvm/test/guide/ -knit.pattern=example-[a-zA-Z0-9-]+-##\\.kt -knit.include=knit.code.include test.package=kotlinx.coroutines.guide.test test.dir=../kotlinx-coroutines-core/jvm/test/guide/test/ -test.template=knit.test.template -# Various test validation modes and their corresponding methods from TestUtil -test.mode.=verifyLines -test.mode.STARTS_WITH=verifyLinesStartWith -test.mode.ARBITRARY_TIME=verifyLinesArbitraryTime -test.mode.FLEXIBLE_TIME=verifyLinesFlexibleTime -test.mode.FLEXIBLE_THREAD=verifyLinesFlexibleThread -test.mode.LINES_START_UNORDERED=verifyLinesStartUnordered -test.mode.LINES_START=verifyLinesStart -test.mode.EXCEPTION=verifyExceptions \ No newline at end of file diff --git a/docs/knit.test.template b/docs/knit.test.template index a912555a43..727493c662 100644 --- a/docs/knit.test.template +++ b/docs/knit.test.template @@ -5,6 +5,7 @@ // This file was automatically generated from ${file.name} by Knit tool. Do not edit. package ${test.package} +import kotlinx.coroutines.knit.* import org.junit.Test class ${test.name} { diff --git a/gradle.properties b/gradle.properties index 238a9c6ac9..196a4a9ac0 100644 --- a/gradle.properties +++ b/gradle.properties @@ -10,7 +10,7 @@ kotlin_version=1.4.0 # Dependencies junit_version=4.12 atomicfu_version=0.14.4 -knit_version=0.1.3 +knit_version=0.2.0 html_version=0.6.8 lincheck_version=2.7.1 dokka_version=0.9.16-rdev-2-mpp-hacks diff --git a/knit.properties b/knit.properties new file mode 100644 index 0000000000..bc177ce44c --- /dev/null +++ b/knit.properties @@ -0,0 +1,16 @@ +# +# Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. +# + +knit.include=docs/knit.code.include +test.template=docs/knit.test.template + +# Various test validation modes and their corresponding methods from TestUtil +test.mode.=verifyLines +test.mode.STARTS_WITH=verifyLinesStartWith +test.mode.ARBITRARY_TIME=verifyLinesArbitraryTime +test.mode.FLEXIBLE_TIME=verifyLinesFlexibleTime +test.mode.FLEXIBLE_THREAD=verifyLinesFlexibleThread +test.mode.LINES_START_UNORDERED=verifyLinesStartUnordered +test.mode.LINES_START=verifyLinesStart +test.mode.EXCEPTION=verifyExceptions \ No newline at end of file diff --git a/kotlinx-coroutines-core/common/src/flow/operators/Delay.kt b/kotlinx-coroutines-core/common/src/flow/operators/Delay.kt index 5f3c900c1b..aa55fea721 100644 --- a/kotlinx-coroutines-core/common/src/flow/operators/Delay.kt +++ b/kotlinx-coroutines-core/common/src/flow/operators/Delay.kt @@ -14,13 +14,30 @@ import kotlinx.coroutines.selects.* import kotlin.jvm.* import kotlin.time.* +/* Scaffolding for Knit code examples + + +*/ + /** * Returns a flow that mirrors the original flow, but filters out values * that are followed by the newer values within the given [timeout][timeoutMillis]. * The latest value is always emitted. * * Example: - * ``` + * + * ```kotlin * flow { * emit(1) * delay(90) @@ -33,7 +50,14 @@ import kotlin.time.* * emit(5) * }.debounce(1000) * ``` - * produces `3, 4, 5`. + * + * + * produces the following emissions + * + * ```text + * 3, 4, 5 + * ``` + * * * Note that the resulting flow does not emit anything as long as the original flow emits * items faster than every [timeoutMillis] milliseconds. @@ -77,7 +101,8 @@ public fun Flow.debounce(timeoutMillis: Long): Flow { * The latest value is always emitted. * * Example: - * ``` + * + * ```kotlin * flow { * emit(1) * delay(90.milliseconds) @@ -90,7 +115,14 @@ public fun Flow.debounce(timeoutMillis: Long): Flow { * emit(5) * }.debounce(1000.milliseconds) * ``` - * produces `3, 4, 5`. + * + * + * produces the following emissions + * + * ```text + * 3, 4, 5 + * ``` + * * * Note that the resulting flow does not emit anything as long as the original flow emits * items faster than every [timeout] milliseconds. @@ -103,15 +135,23 @@ public fun Flow.debounce(timeout: Duration): Flow = debounce(timeout.t * Returns a flow that emits only the latest value emitted by the original flow during the given sampling [period][periodMillis]. * * Example: - * ``` + * + * ```kotlin * flow { * repeat(10) { * emit(it) - * delay(50) + * delay(110) * } - * }.sample(100) + * }.sample(200) + * ``` + * + * + * produces the following emissions + * + * ```text + * 1, 3, 5, 7, 9 * ``` - * produces `1, 3, 5, 7, 9`. + * * * Note that the latest element is not emitted if it does not fit into the sampling window. */ @@ -166,15 +206,23 @@ internal fun CoroutineScope.fixedPeriodTicker(delayMillis: Long, initialDelayMil * Returns a flow that emits only the latest value emitted by the original flow during the given sampling [period]. * * Example: - * ``` + * + * ```kotlin * flow { * repeat(10) { * emit(it) - * delay(50.milliseconds) + * delay(110.milliseconds) * } - * }.sample(100.milliseconds) + * }.sample(200.milliseconds) + * ``` + * + * + * produces the following emissions + * + * ```text + * 1, 3, 5, 7, 9 * ``` - * produces `1, 3, 5, 7, 9`. + * * * Note that the latest element is not emitted if it does not fit into the sampling window. */ diff --git a/kotlinx-coroutines-core/jvm/test/examples/example-delay-01.kt b/kotlinx-coroutines-core/jvm/test/examples/example-delay-01.kt new file mode 100644 index 0000000000..d2a5d536b2 --- /dev/null +++ b/kotlinx-coroutines-core/jvm/test/examples/example-delay-01.kt @@ -0,0 +1,24 @@ +/* + * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +// This file was automatically generated from Delay.kt by Knit tool. Do not edit. +package kotlinx.coroutines.examples.exampleDelay01 + +import kotlinx.coroutines.* +import kotlinx.coroutines.flow.* + +fun main() = runBlocking { + +flow { + emit(1) + delay(90) + emit(2) + delay(90) + emit(3) + delay(1010) + emit(4) + delay(1010) + emit(5) +}.debounce(1000) +.toList().joinToString().let { println(it) } } diff --git a/kotlinx-coroutines-core/jvm/test/examples/example-delay-02.kt b/kotlinx-coroutines-core/jvm/test/examples/example-delay-02.kt new file mode 100644 index 0000000000..1b6b12f041 --- /dev/null +++ b/kotlinx-coroutines-core/jvm/test/examples/example-delay-02.kt @@ -0,0 +1,19 @@ +/* + * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +// This file was automatically generated from Delay.kt by Knit tool. Do not edit. +package kotlinx.coroutines.examples.exampleDelay02 + +import kotlinx.coroutines.* +import kotlinx.coroutines.flow.* + +fun main() = runBlocking { + +flow { + repeat(10) { + emit(it) + delay(110) + } +}.sample(200) +.toList().joinToString().let { println(it) } } diff --git a/kotlinx-coroutines-core/jvm/test/examples/example-delay-duration-01.kt b/kotlinx-coroutines-core/jvm/test/examples/example-delay-duration-01.kt new file mode 100644 index 0000000000..a19e6cb181 --- /dev/null +++ b/kotlinx-coroutines-core/jvm/test/examples/example-delay-duration-01.kt @@ -0,0 +1,26 @@ +@file:OptIn(ExperimentalTime::class) +/* + * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +// This file was automatically generated from Delay.kt by Knit tool. Do not edit. +package kotlinx.coroutines.examples.exampleDelayDuration01 + +import kotlin.time.* +import kotlinx.coroutines.* +import kotlinx.coroutines.flow.* + +fun main() = runBlocking { + +flow { + emit(1) + delay(90.milliseconds) + emit(2) + delay(90.milliseconds) + emit(3) + delay(1010.milliseconds) + emit(4) + delay(1010.milliseconds) + emit(5) +}.debounce(1000.milliseconds) +.toList().joinToString().let { println(it) } } diff --git a/kotlinx-coroutines-core/jvm/test/examples/example-delay-duration-02.kt b/kotlinx-coroutines-core/jvm/test/examples/example-delay-duration-02.kt new file mode 100644 index 0000000000..e43dfd1e05 --- /dev/null +++ b/kotlinx-coroutines-core/jvm/test/examples/example-delay-duration-02.kt @@ -0,0 +1,21 @@ +@file:OptIn(ExperimentalTime::class) +/* + * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +// This file was automatically generated from Delay.kt by Knit tool. Do not edit. +package kotlinx.coroutines.examples.exampleDelayDuration02 + +import kotlin.time.* +import kotlinx.coroutines.* +import kotlinx.coroutines.flow.* + +fun main() = runBlocking { + +flow { + repeat(10) { + emit(it) + delay(110.milliseconds) + } +}.sample(200.milliseconds) +.toList().joinToString().let { println(it) } } diff --git a/kotlinx-coroutines-core/jvm/test/examples/test/FlowDelayTest.kt b/kotlinx-coroutines-core/jvm/test/examples/test/FlowDelayTest.kt new file mode 100644 index 0000000000..226d31cc00 --- /dev/null +++ b/kotlinx-coroutines-core/jvm/test/examples/test/FlowDelayTest.kt @@ -0,0 +1,39 @@ +/* + * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +// This file was automatically generated from Delay.kt by Knit tool. Do not edit. +package kotlinx.coroutines.examples.test + +import kotlinx.coroutines.knit.* +import org.junit.Test + +class FlowDelayTest { + @Test + fun testExampleDelay01() { + test("ExampleDelay01") { kotlinx.coroutines.examples.exampleDelay01.main() }.verifyLines( + "3, 4, 5" + ) + } + + @Test + fun testExampleDelayDuration01() { + test("ExampleDelayDuration01") { kotlinx.coroutines.examples.exampleDelayDuration01.main() }.verifyLines( + "3, 4, 5" + ) + } + + @Test + fun testExampleDelay02() { + test("ExampleDelay02") { kotlinx.coroutines.examples.exampleDelay02.main() }.verifyLines( + "1, 3, 5, 7, 9" + ) + } + + @Test + fun testExampleDelayDuration02() { + test("ExampleDelayDuration02") { kotlinx.coroutines.examples.exampleDelayDuration02.main() }.verifyLines( + "1, 3, 5, 7, 9" + ) + } +} diff --git a/kotlinx-coroutines-core/jvm/test/guide/test/BasicsGuideTest.kt b/kotlinx-coroutines-core/jvm/test/guide/test/BasicsGuideTest.kt index 7fc57c2ee3..ea5003b0c7 100644 --- a/kotlinx-coroutines-core/jvm/test/guide/test/BasicsGuideTest.kt +++ b/kotlinx-coroutines-core/jvm/test/guide/test/BasicsGuideTest.kt @@ -5,6 +5,7 @@ // This file was automatically generated from basics.md by Knit tool. Do not edit. package kotlinx.coroutines.guide.test +import kotlinx.coroutines.knit.* import org.junit.Test class BasicsGuideTest { diff --git a/kotlinx-coroutines-core/jvm/test/guide/test/CancellationGuideTest.kt b/kotlinx-coroutines-core/jvm/test/guide/test/CancellationGuideTest.kt index a2e91de82d..9e8cd28f16 100644 --- a/kotlinx-coroutines-core/jvm/test/guide/test/CancellationGuideTest.kt +++ b/kotlinx-coroutines-core/jvm/test/guide/test/CancellationGuideTest.kt @@ -5,6 +5,7 @@ // This file was automatically generated from cancellation-and-timeouts.md by Knit tool. Do not edit. package kotlinx.coroutines.guide.test +import kotlinx.coroutines.knit.* import org.junit.Test class CancellationGuideTest { diff --git a/kotlinx-coroutines-core/jvm/test/guide/test/ChannelsGuideTest.kt b/kotlinx-coroutines-core/jvm/test/guide/test/ChannelsGuideTest.kt index 209d439663..d15a550adb 100644 --- a/kotlinx-coroutines-core/jvm/test/guide/test/ChannelsGuideTest.kt +++ b/kotlinx-coroutines-core/jvm/test/guide/test/ChannelsGuideTest.kt @@ -5,6 +5,7 @@ // This file was automatically generated from channels.md by Knit tool. Do not edit. package kotlinx.coroutines.guide.test +import kotlinx.coroutines.knit.* import org.junit.Test class ChannelsGuideTest { diff --git a/kotlinx-coroutines-core/jvm/test/guide/test/ComposingGuideTest.kt b/kotlinx-coroutines-core/jvm/test/guide/test/ComposingGuideTest.kt index 50c3fd7e62..1f9692d56b 100644 --- a/kotlinx-coroutines-core/jvm/test/guide/test/ComposingGuideTest.kt +++ b/kotlinx-coroutines-core/jvm/test/guide/test/ComposingGuideTest.kt @@ -5,6 +5,7 @@ // This file was automatically generated from composing-suspending-functions.md by Knit tool. Do not edit. package kotlinx.coroutines.guide.test +import kotlinx.coroutines.knit.* import org.junit.Test class ComposingGuideTest { diff --git a/kotlinx-coroutines-core/jvm/test/guide/test/DispatcherGuideTest.kt b/kotlinx-coroutines-core/jvm/test/guide/test/DispatcherGuideTest.kt index c0c32410d5..d6f1c21dc0 100644 --- a/kotlinx-coroutines-core/jvm/test/guide/test/DispatcherGuideTest.kt +++ b/kotlinx-coroutines-core/jvm/test/guide/test/DispatcherGuideTest.kt @@ -5,6 +5,7 @@ // This file was automatically generated from coroutine-context-and-dispatchers.md by Knit tool. Do not edit. package kotlinx.coroutines.guide.test +import kotlinx.coroutines.knit.* import org.junit.Test class DispatcherGuideTest { diff --git a/kotlinx-coroutines-core/jvm/test/guide/test/ExceptionsGuideTest.kt b/kotlinx-coroutines-core/jvm/test/guide/test/ExceptionsGuideTest.kt index c42ba31d3a..f34fd3f83b 100644 --- a/kotlinx-coroutines-core/jvm/test/guide/test/ExceptionsGuideTest.kt +++ b/kotlinx-coroutines-core/jvm/test/guide/test/ExceptionsGuideTest.kt @@ -5,6 +5,7 @@ // This file was automatically generated from exception-handling.md by Knit tool. Do not edit. package kotlinx.coroutines.guide.test +import kotlinx.coroutines.knit.* import org.junit.Test class ExceptionsGuideTest { diff --git a/kotlinx-coroutines-core/jvm/test/guide/test/FlowGuideTest.kt b/kotlinx-coroutines-core/jvm/test/guide/test/FlowGuideTest.kt index 7fa9cc84dd..c7d4a72082 100644 --- a/kotlinx-coroutines-core/jvm/test/guide/test/FlowGuideTest.kt +++ b/kotlinx-coroutines-core/jvm/test/guide/test/FlowGuideTest.kt @@ -5,6 +5,7 @@ // This file was automatically generated from flow.md by Knit tool. Do not edit. package kotlinx.coroutines.guide.test +import kotlinx.coroutines.knit.* import org.junit.Test class FlowGuideTest { diff --git a/kotlinx-coroutines-core/jvm/test/guide/test/SelectGuideTest.kt b/kotlinx-coroutines-core/jvm/test/guide/test/SelectGuideTest.kt index e3f47b9648..55650d4c6a 100644 --- a/kotlinx-coroutines-core/jvm/test/guide/test/SelectGuideTest.kt +++ b/kotlinx-coroutines-core/jvm/test/guide/test/SelectGuideTest.kt @@ -5,6 +5,7 @@ // This file was automatically generated from select-expression.md by Knit tool. Do not edit. package kotlinx.coroutines.guide.test +import kotlinx.coroutines.knit.* import org.junit.Test class SelectGuideTest { diff --git a/kotlinx-coroutines-core/jvm/test/guide/test/SharedStateGuideTest.kt b/kotlinx-coroutines-core/jvm/test/guide/test/SharedStateGuideTest.kt index 8d534a09ea..3162b24cbc 100644 --- a/kotlinx-coroutines-core/jvm/test/guide/test/SharedStateGuideTest.kt +++ b/kotlinx-coroutines-core/jvm/test/guide/test/SharedStateGuideTest.kt @@ -5,6 +5,7 @@ // This file was automatically generated from shared-mutable-state-and-concurrency.md by Knit tool. Do not edit. package kotlinx.coroutines.guide.test +import kotlinx.coroutines.knit.* import org.junit.Test class SharedStateGuideTest { diff --git a/kotlinx-coroutines-core/jvm/test/guide/test/TestUtil.kt b/kotlinx-coroutines-core/jvm/test/knit/TestUtil.kt similarity index 98% rename from kotlinx-coroutines-core/jvm/test/guide/test/TestUtil.kt rename to kotlinx-coroutines-core/jvm/test/knit/TestUtil.kt index fb1c85bce1..7eda9043db 100644 --- a/kotlinx-coroutines-core/jvm/test/guide/test/TestUtil.kt +++ b/kotlinx-coroutines-core/jvm/test/knit/TestUtil.kt @@ -1,8 +1,8 @@ /* - * Copyright 2016-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. */ -package kotlinx.coroutines.guide.test +package kotlinx.coroutines.knit import kotlinx.coroutines.* import kotlinx.coroutines.internal.* diff --git a/kotlinx-coroutines-core/knit.properties b/kotlinx-coroutines-core/knit.properties new file mode 100644 index 0000000000..93ce87db8f --- /dev/null +++ b/kotlinx-coroutines-core/knit.properties @@ -0,0 +1,10 @@ +# +# Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. +# + +knit.package=kotlinx.coroutines.examples +knit.dir=jvm/test/examples/ + +test.package=kotlinx.coroutines.examples.test +test.dir=jvm/test/examples/test/ +