Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/olical/prepl-compliance-test

Checks a Clojure prepl server against a bunch of tests
https://github.com/olical/prepl-compliance-test

clojure clojurescript prepl

Last synced: 17 days ago
JSON representation

Checks a Clojure prepl server against a bunch of tests

Awesome Lists containing this project

README 

        
= prepl compliance test



____

This project is still in early development, feel free to contribute more tests! It's usable in it's current state but is pretty unforgiving, the tests need to be tweaked to make them a little more leniant on some things I think, I'll see.

____



A test suite to check a given https://clojure.org/[Clojure] prepl server for compliance as I've defined in https://oli.me.uk/clojure-prepl-for-tool-authors/[Clojure prepl for tool authors].



== Why?



Tool authors are beginning to add prepl servers to their projects (https://github.com/thheller/shadow-cljs/issues/508[shadow-cljs!]) but it's not a documented technology and it's full of small nuances. I've been hacking on prepls for well over a year now so I'm trying to capture that knowledge in a program that others can use to catch inconsistencies before they become issues raised by your users.



My goal for this project is to provide an easy way for someone implementing a prepl server to check that they're in line with all of the other implementations. That isn't to say even the official prepl servers from Clojure and ClojureScript are 100% correct yet, there's even inconsistencies there! This framework will hopefully give us a good starting point for talking about and improving prepls in the Clojure world.



These tests are the _ideal_ scenario, it'll take a while for us all to get there.



== Installation



The easiest way to use this tool for now is to clone the repository and execute it from the source. You _could_ refer to it as a git dependency in your `deps.edn` and execute `prepl-compliance-test.main/-main` but that seems kind of unnecessary to me.



== Usage



Start the prepl server you wish to check, you could start one for Clojure or ClojureScript quite easily with https://github.com/Olical/propel[Propel]. Refer to https://oli.me.uk/repling-into-projects-with-prepl-and-propel/[REPLing into projects with prepl and Propel] for more information of starting prepls of various kinds.



You can start a baseline example server by executing `scripts/baseline.sh`. This is a regular Clojure prepl server but it'll serve as a decent example.



Once that's up we can execute the test suite against it like so:



[source,sh]

----

scripts/run.sh localhost 33945

----



Where `33945` is the port the baseline server was started on. Change these arguments to whatever you've configured for your prepl server.



== Development



If you'd like to add more tests to this suite (please do!) you can start the development prepl with `scripts/dev.sh`, I then connect to this with my own https://neovim.io/[Neovim] tooling, https://github.com/Olical/conjure[Conjure].



You could also just run `scripts/run.sh` repeatedly until you have the desired result. If you wish to use nREPL to develop this project, feel free to add the configuration required. I haven't added it because I don't use nREPL based tooling but I have nothing against it being added.



== Unlicenced



Find the full http://unlicense.org/[unlicense] in the `UNLICENSE` file, but here's a snippet.



____

This is free and unencumbered software released into the public domain.



Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means.

____