How to set up initial state for StateFlow tests?

Use the :init option in state-flow.api/run* to provide a function that builds the state, often based on system components like Stuart Sierra's Component library, as shown in the README examples with {:init build-initial-state}.

StateFlow vs clojure.test for integration testing?

StateFlow extends clojure.test with composable steps and state management, making it ideal for complex backend integration tests, whereas plain clojure.test is better for straightforward unit tests without state flow needs.

How to handle async tests with StateFlow?

Use the :times-to-try and :sleep-time options in the match? macro to retry assertions until they succeed, which is useful for testing asynchronous operations like database updates or concurrent processes.

What are best practices for writing StateFlow helpers?

Start with functions from state-flow.api, compose steps using bindings for readability, and encapsulate domain-specific logic, as demonstrated in the HTTP helper example in the README for webapp testing.

How to migrate from older versions of StateFlow?

Follow the provided refactor script for match? signature changes, as detailed in the upgrade note for state-flow-2.2.4, which helps automate the transition but still requires manual adjustments in test code.

Can StateFlow be used with Midje?

Yes, StateFlow includes Midje support through the verify function, allowing fact-like assertions within flows, as shown in the README example for checking data persistence after operations.

Open-Awesome

StateFlow

MITClojure

A Clojure testing framework using a state monad for composing reusable integration test steps.

GitHub

390 stars15 forks0 contributors

What is StateFlow?

StateFlow is a Clojure testing framework designed for integration testing by using a state monad to build and compose test flows. It allows developers to create reusable test steps and bindings, making it easier to write and maintain complex integration tests. The framework integrates with clojure.test and matcher-combinators, providing a structured approach to testing backend systems.

Target Audience

Clojure developers building backend services who need a robust framework for integration testing with composable test steps and state management.

Value Proposition

Developers choose StateFlow for its state monad foundation, which enables predictable test composition and reuse, reducing boilerplate and improving test clarity. Its integration with clojure.test and support for asynchronous testing make it a powerful tool for backend integration tests.

Overview

Integration testing framework using a state monad in the backend for building and composing flows

Use Cases

Best For

Writing integration tests for Clojure backend services
Composing reusable test steps to reduce duplication
Testing systems with stateful components like databases or HTTP services
Handling asynchronous or concurrent operations in tests
Building maintainable test suites with clear step composition
Integrating with clojure.test and matcher-combinators for assertions

Not Ideal For

Projects requiring simple unit tests without state management
Frontend or UI testing where JavaScript frameworks are needed
Teams unfamiliar with monads or functional programming concepts in Clojure
Rapid prototyping where quick test setup without configuration overhead is essential

Pros & Cons

Pros

Monadic State Management

Uses a state monad to pass and manage state between test steps, enabling predictable and composable data flow, as described in the README where steps are functions of state.

Composable Test Flows

Allows building complex integration tests by combining primitive steps and nested flows, following the Composite Pattern for modular and reusable test code.

Integrated Assertion Support

Seamlessly integrates with clojure.test and matcher-combinators via defflow and match? macros, providing powerful assertions with retry logic for asynchronous testing.

Asynchronous Handling

Supports concurrency with :times-to-try and :sleep-time options in match?, enabling robust testing of operations like database updates or message processing.

Cons

Monad Learning Curve

Requires understanding of monadic concepts and the funcool.cats library, which can be a barrier for developers new to functional programming in Clojure.

Complex Initial Setup

Setting up the initial state, especially with systems using Component libraries, adds configuration overhead that may be cumbersome for simple test suites.

Breaking Changes

Upgrades like state-flow-2.2.4 introduced signature changes for match?, requiring refactoring with provided scripts, which can disrupt existing test code.

Frequently Asked Questions

Related Projects

Midje

Midje provides a migration path from clojure.test to a more flexible, readable, abstract, and gracious style of testing

Stars1,698

Forks128

Last commit2 years ago

kaocha

Full featured next gen Clojure test runner

Stars866

Forks82

Last commit1 year ago

Expectations

A minimalist's unit testing framework ("classic" version)

Stars398

Forks25

Last commit3 years ago

test-doubles

A small spying and stubbing library for Clojure and ClojureScript

Stars36

Forks4

Last commit5 years ago

Community-curated · Updated weekly · 100% open source

Found a gem we're missing?

Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.

Submit a project Star on GitHub