Lightweight library for explicit and unit testable multithreading in Android.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
gradle/wrapper
sample
threadposter
.gitignore
LICENSE.txt
README.md
build.gradle
gradle.properties
gradlew
gradlew.bat
settings.gradle

README.md

ThreadPoster

Lightweight library for unit testable and expressive multi-threading in Android.

ThreadPoster is in public beta. I'm actively looking for feedback on project's structure, naming and usability. Bug reports are also welcome, of course.

Install

To use ThreadPoster in your project, add this line to your Gradle dependencies configuration:

implementation 'com.techyourchance.threadposter:threadposter:0.8.2'

Usage

At the core of this library are two simple classes: UiThreadPoster and BackgroundThreadPoster.

Code style note: if you're concerned with "boilerplate", you can replace explicit Runnables in the examples below with lambdas.

Executing code on UI thread

In the following example, updateText(String) can be safely called on any thread. The actual UI update will always take place on UI thread:

public class TextUpdater {

    private final UiThreadPoster mUiThreadPoster;
    private final TextView mTxtSample;
    
    public void updateText(final String text) {
        mUiThreadPoster.post(new Runnable() {
            @Override
            public void run() {
                mTxtSample.setText(text);
            }
        });
    }
}

Executing code on "background" thread

In the following example, fetchAndCacheUserDetails(String) can be safely called on any thread. The actual network request and data caching will always take place on background thread (non-UI thread):

public class UpdateUserDetailsUseCase {

    private final BackgroundThreadPoster mBackgroundThreadPoster;
    private final UserDetailsEndpoint mUserDetailsEndpoint;
    private final UserDetailsCache mUserDetailsCache;

    public void fetchAndCacheUserDetails(final String userId) {
        mBackgroundThreadPoster.post(new Runnable() {
            @Override
            public void run() {
                UserDetails userDetails = mUserDetailsEndpoint.fetchUserDetails(userId);
                mUserDetailsCache.cacheUserDetails(userDetails);
            }
        });
    }
}

Executing code on "background" thread and notifying Observers on UI thread

In the following example, fetchData() can be safely called on any thread. The actual data fetch will always take place on background thread, and the observers will always be notified on UI thread:

public class FetchDataUseCase {

    public interface Listener {
        void onDataFetched(String data);
        void onDataFetchFailed();
    }

    private final FakeDataFetcher mFakeDataFetcher;
    private final BackgroundThreadPoster mBackgroundThreadPoster;
    private final UiThreadPoster mUiThreadPoster;

    public void fetchData() {
        // offload work to background thread
        mBackgroundThreadPoster.post(new Runnable() {
            @Override
            public void run() {
                fetchDataSync();
            }
        });
    }

    @WorkerThread
    private void fetchDataSync() {
        try {
            final String data = mFakeDataFetcher.getData();
            mUiThreadPoster.post(new Runnable() { // notify listeners on UI thread
                @Override
                public void run() {
                    notifySuccess(data);
                }
            });
        } catch (FakeDataFetcher.DataFetchException e) {
            mUiThreadPoster.post(new Runnable() { // notify listeners on UI thread
                @Override
                public void run() {
                    notifyFailure();
                }
            });
        }

    }

    @UiThread
    private void notifyFailure() {
        for (Listener listener : mListeners) {
            listener.onDataFetchFailed();
        }
    }

    @UiThread
    private void notifySuccess(String data) {
        for (Listener listener : mListeners) {
            listener.onDataFetched(data);
        }
    }

}

Unit Testing

This library allows for easy unit testing of multithreaded code.

Important note: no amount of unit testing can guarantee that your code is thread-safe. In other words, even if your unit tests pass, your code can still be subject to race conditions, deadlocks, livelocks, etc.

To support unit testing, ThreadPosters library is shipped with test double implementations for both UiThreadPoster and BackgroundThreadPoster. The core feature of these test doubles is that they are truly multi-threaded. In other words, when you unit test using these test doubles, you exercise your code in real multi-threaded environment which is the best approximation of the real production setting.

Benefits and drawbacks of multi-threaded unit testing

The approach employed by ThreadPoster's test doubles has its benefits and drawbacks.

Benefits of multi-threaded unit testing:

  1. Exercises the code in real production setting.
  2. Has a chance to find multi-threading bugs. This will manifest itself in the form of "flaky" tests (tests that fail ocassionally).

Drawbacks of multi-threaded unit testing:

  1. Longer unit tests execution times.
  2. Requires user assistance in the form of an additional step in each test case (join() calls in the examples below).

On my machine, test cases that use ThreadPoster test doubles execute in ~10ms (as opposed to <1ms for plain Java). That's not an issue if you have 100 multi-threaded test cases, but it's a show stopper for proper TDD if you have 1000.

The upside is that absolute majority of your classes shoudln't be multi-threaded, which means that the overall percentage of slow unit tests should be low.

I'm currently working on ways to optimize the test times, but you should definitely keep this drawback in mind if you intend to unit test using ThreadPoster test doubles.

Example unit test

Below code shows a unit test that makes use of ThreadPoster test doubles. It's part of the sample project.

Note the calls to mThreadPostersTestDouble.join() in tests - that's the drawback number two. Since test cases become multithreaded, JUnit can't control tests' execution by itself anymore. Therefore, you'll need to call mThreadPostersTestDouble.join() before the assertions stage in each of your test cases. This makes sure that all involved threads run to completion and their side effects will be visible during assertions stage.

public class FetchDataUseCaseTest {

    private static final String TEST_DATA = "testData";

    private ThreadPostersTestDouble mThreadPostersTestDouble = new ThreadPostersTestDouble();

    private FakeDataFetcher mFakeDataFetcherMock;
    private FetchDataUseCase.Listener mListener1;
    private FetchDataUseCase.Listener mListener2;

    private FetchDataUseCase SUT;

    @Before
    public void setup() throws Exception {
        mFakeDataFetcherMock = mock(FakeDataFetcher.class);

        SUT = new FetchDataUseCase(
                mFakeDataFetcherMock,
                mThreadPostersTestDouble.getBackgroundTestDouble(),
                mThreadPostersTestDouble.getUiTestDouble());

        mListener1 = mock(FetchDataUseCase.Listener.class);
        mListener2 = mock(FetchDataUseCase.Listener.class);
    }

    @Test
    public void fetchData_successNoListeners_completesWithoutErrors() throws Exception {
        // Arrange
        success();
        // Act
        SUT.fetchData();
        // Assert

        // needs to be called before assertions in order for all threads to complete and
        // all side effects to be present
        mThreadPostersTestDouble.join();

        assertThat(true, is(true));
    }

    @Test
    public void fetchData_successMultipleListeners_notifiedWithCorrectData() throws Exception {
        // Arrange
        success();
        ArgumentCaptor<String> ac = ArgumentCaptor.forClass(String.class);
        // Act
        SUT.registerListener(mListener1);
        SUT.registerListener(mListener2);
        SUT.fetchData();
        // Assert

        // needs to be called before assertions in order for all threads to complete and
        // all side effects to be present
        mThreadPostersTestDouble.join();

        verify(mListener1).onDataFetched(ac.capture());
        verify(mListener2).onDataFetched(ac.capture());
        List<String> dataList = ac.getAllValues();
        assertThat(dataList.get(0), is(TEST_DATA));
        assertThat(dataList.get(1), is(TEST_DATA));
    }

    @Test
    public void fetchData_failureMultipleListeners_notifiedOfFailure() throws Exception {
        // Arrange
        failure();
        // Act
        SUT.registerListener(mListener1);
        SUT.registerListener(mListener2);
        SUT.fetchData();
        // Assert

        // needs to be called before assertions in order for all threads to complete and
        // all side effects to be present
        mThreadPostersTestDouble.join();

        verify(mListener1).onDataFetchFailed();
        verify(mListener2).onDataFetchFailed();
    }

    // ---------------------------------------------------------------------------------------------
    // Helper methods
    // ---------------------------------------------------------------------------------------------

    private void success() throws FakeDataFetcher.DataFetchException {
        when(mFakeDataFetcherMock.getData()).thenReturn(TEST_DATA);
    }

    private void failure() throws FakeDataFetcher.DataFetchException {
        doThrow(new FakeDataFetcher.DataFetchException()).when(mFakeDataFetcherMock).getData();
    }
}

License

This project is licensed under the Apache-2.0 License - see the LICENSE.txt file for details