clojurephant / jovial

JUnit Platform test engines for Clojure

clojurephant

Formerly known as "gradle-clojure"

What is this?

A Gradle plugin providing support for the Clojure and ClojureScript languages.

NOTE: clojurephant should not be considered stable until 1.0.0. Until then, minor versions (e.g. 0.1.0 to 0.2.0) will likely contain breaking changes.

Clojure Features

• Packaging Clojure code (and/or AOT compiled classes) into a JAR
• Package an Uberjar (via the Gradle Shadow plugin)
• AOT compilation
• Running clojure.test tests (integrated into Gradle's Test task)
• Running an nREPL server (supports custom middlewares or handler)

ClojureScript Features

NOTE: ClojureScript features are pretty new, so let us know if you run into issues or have ideas for improvement.

• Packaging Clojure code (or compiled JS) into a JAR or ZIP
• ClojureScript compilation (multiple builds supported)

Why should you care?

The goal is to provide the same creature comforts that Leiningen and Boot do for Clojure/ClojureScript development, while also leveraging Gradle's unique features:

• Strong support for polyglot projects
• Strong support for multi-project builds
• Large plugin ecosystem

Usage

See the Release Notes for available versions, compatibility with Gradle, Java, and Clojure, and detailed change notes.

This plugin assumes you're using a sane layout for your Clojure code - namespaces corresponding to your source code layout, and one namespace per file. The plugin uses the filenames to calculate the namespaces involved, it does not parse the files looking for ns forms.

Quick Start

Look at our sample projects:

• Clojure Library
• Clojure Application
• ClojureScript Application

Common Commands

• ./gradlew test Executes your clojure.test tests (and any other JUnit tests in your build).
• ./gradlew clojureRepl Starts an nREPL server (on a random port by default).

build.gradle

plugins {
  id "dev.clojurephant.clojure" version "<version>"
}

// You need to add clojars for the plugin to work.
repositories {
  maven {
    name = 'Clojars' // name can be ommitted, but is helpful in troubleshooting
    url = 'https://repo.clojars.org/'
  }
}

dependencies {
  // requires a version of Clojure with prepl (1.10+)
  implementation 'org.clojure:clojure:1.11.1'
  // and any other dependencies you want on the compile classpath
  // implementation 'group:artifact:version'

  // needed for test integration
  testRuntimeOnly 'dev.clojurephant:jovial:0.4.2'
  // and any other test-specific dependencies
  // testImplementation 'group:artifact:version'

  // dependencies for REPL use only
  devImplementation 'org.clojure:tools.namespace:1.3.0'
}

// needed for test integration
tasks.withType(Test) {
  useJUnitPlatform()
}

See all available options in the docs.

Getting help

Read the online Clojurephant documentation https://clojurephant.dev.

For questions or support, please visit the Clojurephant Discussions, ClojureVerse gradle-clojure channel or the Clojurian's Slack #gradle channel

For bug reports and feature requests, please use the repo's issues.

Contributing

See the guidelines for details on how you can contribute.

Acknowledgements

This project started from the cursive.clojure plugin by Colin Fleming (@cmf, original author) and Piotrek Bzdyl (@pbzdyl).

Thanks to John Szakmeister (@jszakmeister) for organizing a call with Gradle to get us started in the right direction.

Thanks to all our contributors.

jovial's Issues

Update to JUnit's M1 release

Should be able to use TestLauncher from Gradle tooling api

Not sure exactly how to do this. But thinking the test task would need to take a ListenerManager and get the TestListener and TestListenerInternal broadcasts. Could send the messages there. The ClientFowardingTestListener seems to be the one that sends back to the tooling consumer.

What to do with opentest4j?

OpenTest4J

Plugin for leiningen to run JUnit 5 engines

Engine for midje

Plugin for Gradle using JUnit5 launcher and Gradle model space

Implementation

...

Functional Requirements

• The JUnit5 engine can be used
• The JUnit4 engine can be used
• The clojure.test engine can be used
• Arbitrary combintations work
• Can filter tests from command line option (like the --tests)
• Can filter tests from the task config
• Tooling API can see the test descriptors
• Tooling API can launch tests from the descriptors

Plugin for Clojure REPL to run JUnit5 engines

Jovial should call all reporting hooks that clojure.test does

Jovial currently creates a pretty simple reporter that focuses on printing exceptions to the output stream. Because of this we didn't bother calling (do-report ...) in all of the places clojure.test does, which prevents a custom reporter from handling those event types.

Discussed in clojurephant/clojurephant#214

^{Originally posted by ngrewe February 17, 2024}
Hi folks,

I'm porting an older project that previously relied on the clojuresque gradle plugin to clojurephant, and I'm running into a bit of a problem with the JUnit integration. My test suite defines a custom report hook for :end-test-var. When I execute the test suite in IntelliJ using Cursive, that method instead gets called as expected, but when executing ./gradlew test (using the Jovial integration), it isn't called. Can anybody point me towards why that might be happening and how to fix it? I've already tried using (defmethod dev.clojurephant.jovial.engine.clojure-test/jovial-report :end-test-var …) instead of (defmethod clojure.test/report :end-test-var …), but to no avail.

Thanks,

Niels

Implementation

Looks like (at a minimum) we'll need to replicate how clojure.test calls begin/end around testing the var. I think we'd just need to add it in here.

Open to suggestions on if/how we make this extensible for end users. The (defmethod dev.clojurephant.jovial.engine.clojure-test/jovial-report :end-test-var …) that you tried is the most straightforward, but I hadn't originally intended to have a public API surface to jovial, because ideally running your test via jovial would not impact what you write in your tests. But if there's not a better way to do it transparently, that could still be an option.

More comprehensive test suite for clojure.test

Test suite should cover a bunch of scenarios that aren't covered now:

• Exception during once fixture
• Exception during each fixture
• Assertion failure in test
• Multiple assertion failures in one test
• General validation of listeners firing correctly

Rename this

JUnit5 is now using the name Jupiter, so I don't want to tread on their namespace.

Can use JUnit5's JUnit 4 runner to use the Gradle Test task

• The JUnit5 engine can be used with the JUnit4 runner
• The clojure.test engine can be used with the JUnit4 runner
• Arbitrary combintations work
• Tooling API can see the test descriptors
• Tooling API can launch tests from the descriptors

Engine for speclj

Engine for test.check

If it's different from clojure.test (might be different test detection/reporting that would be worthwhile).

Plugin for boot to run JUnit 5 engines

Engine for clojure.test

• Simple clojure.test tests work
• Testing vars hierarchy preserved
• Testing contexts hierarchy preserved
• Selecting by classpath works
• Selecting by unique id works
• Selecting by namespace works
• Selecting by var works
• Filtering by namespace pattern works
• Expose metadata as tags

Support clojurescript testing?

I added this library to junit third party engine list

Hi,

I added this to https://github.com/junit-team/junit5/wiki/Third-party-Extensions .
I hope it helps.