kotlinx-coroutines-test modules

[pull-vert]

add 3 new dedicated kotlinx-coroutines-test projects (common, JVM and JS)
Solves #336

[elizarov]

I've reviewed this PR and I have few questions or concerns.

There is a number of APIs that were previously internal in core (like resetCoroutineId, CommonPool.usePrivePool, DefaultExecutor.ensureStarted, etc). They are now public which raises a number of issues. The most pressing issue is that they are not documented, but there is also a question on whether these low-level methods and classes should be exposed at all. I feel that some kind of higher-level test-oriented functionality to "setup" and "clear" the library before/after tests should be provided instead.

TestBase class itself provides both general-purpose testing facilities (expect and finish) as well as very project specific things like isStressTest and stressTestMultiplier. I think that they should be decoupled somehow.

[pull-vert]

I understand that making some test API from internal to public is to avoid, I can add a new Kotlin object in kotlin-coroutines-core module

package kotlinx.coroutines.experimental.test

import kotlinx.coroutines.experimental.CommonPool
import kotlinx.coroutines.experimental.DefaultExecutor

public object Tests {

    // used for tests
    public fun usePrivatePool() {
        CommonPool.usePrivatePool()
    }

    // used for tests
    public fun shutdown(shutdownTimeout: Long) {
        CommonPool.shutdown(shutdownTimeout)
        DefaultExecutor.shutdown(shutdownTimeout)
    }
}

And then call it from TestBase in before and after functions in kotlin-coroutines-test module

     private val SHUTDOWN_TIMEOUT = 10_000L // 10s at most to wait

    @Before
    fun before() {
        Tests.usePrivatePool()
        threadsBefore = currentThreads()
    }

    @After
    fun onCompletion() {
        error.get()?.let { throw it }
        check(actionIndex.get() == 0 || finished.get()) { "Expecting that 'finish(...)' was invoked, but it was not" }
        Tests.shutdown(SHUTDOWN_TIMEOUT )
        checkTestThreads(threadsBefore)
    }

Maybe the TestBase class could be splitted in two, first a general-purpose TestBase in module kotlinx-coroutines-test and a StressTest kotlin file in module kotlinx-coroutines-core ( src/test/kotlin) thay provide project specific stress test values

I am planning to integrate TestCoroutineContext in the kotlinx-coroutines-test module too.

[pull-vert]

@elizarov can you review this PR again ?
Your questions and concerns should be ok with this updated MR, feel free to tell me if additional changes should be done.

I think coroutine-guide.md should be completed with a Testing part, describing how to use TestBase and TestCoroutineContext with code examples for nice testing experience with coroutines.
But I don't feel confident enough with my poor english skills to update it.