DEV Community

Cover image for shrun: A modern CLI testing framework

shrun: A modern CLI testing framework

Ryland G on April 13, 2020

TL;DR: Test your CLI commands in isolated docker containers using the Jest test environment you already love. install shrun using npm view shrun ...
Collapse
 
pavelloz profile image
Paweł Kowalski • Edited

Wow... This might be what i was looking for for the past 2 years :))

I need to dive deeper, because my CLI's are often manipulating files on the HDD, so:

input = file
output = processed file

But the whole syntax looks more promising than fiddling with regexps ;)

BTW. Have you tried using alpine or any other docker image that is not measured in GBs?

Collapse
 
taillogs profile image
Ryland G

I'm so happy to hear that shrun might improve your development experience. Manipulating files is definitely not a problem but it may be more tricky if you want to modify files on the host machine from the container. Your point about regexps is spot on, that's what shrun has to do internally so the user doesn't!

I have used many other docker images over the last few years with the tool but haven't used alpine since the rewrite. My implementation doesn't actually care about the specifics of the container as I'm just communicating with the docker daemon directly via HTTP API. Even the default shrun image is much lighter than GB coming in at ~300MB, not tiny but not bad. I'd love to hear more about why image size is important to you.

Thanks for the great feedback and data points.

Collapse
 
pavelloz profile image
Paweł Kowalski

Ouh, right, because input files are outside and output files are outside of container. Hmm. Maybe thats an idea for config option (what to mount where - -v in docker afair).

Hmmm. For some reason when i ran shrun build it started downloading ubuntu 19, which is usually an overkill. :)

Thread Thread
 
taillogs profile image
Ryland G

Wow amazing feedback. Completely agree about allowing users to take advantage of mounting volumes. I immediately opened an issue and think it's one of the higher priority items. github.com/rylandg/shrun/issues/12

As for ubuntu 19. Users are free to bring their own docker image, shrun build is mainly provided as a convenience for those unfamiliar with docker. But I actually use ubuntu 19 for real shrun tests because I want a runtime as close to a real user as possible. This might not make sense for some shrun users but it does for me. Maybe I'll add a few default image options to shrun for users who don't want to make their own but also want some level of control.

Thanks again for the awesome feedback.

Thread Thread
 
taillogs profile image
Ryland G • Edited

I actually went and wrote a quick patch. shrun 0.0.56 now supports a volume flag. May not work perfectly, but should be more than enough to get by. One caveat is that I couldn't use -v flag as it's already used by Jest so I opted for --vo instead. Obviously you can also use --volume. I added an example in the shrun-basic-demo repo of usage here:

github.com/rylandg/shrun-basic-dem...

I'll probably add the option to use an alpine image later today.

Edit: I also just added an alpine image to the repo and reworked build command so it allows you to choose between ubuntu and alpine.

npx shrun build <command-name> --image alpine | ubuntu

Example is in demo repo json github.com/rylandg/shrun-basic-dem... under script name "build-alpine". Not an alpine expert but tried to port all config I use in ubuntu and didn't have trouble with local runs.

Thread Thread
 
pavelloz profile image
Paweł Kowalski

Wow, that was quick :D
Thank you :)

Thread Thread
 
taillogs profile image
Ryland G

No problem. Tbh I was pretty annoyed with myself for not thinking of volumes for the initial release. Thanks so much for mentioning it, should also make nested docker possible.

Collapse
 
hhheath profile image
Heath

Could you explain a little more about the cleanup?: string[] spec stanza? Does it stop/remove the container or just stop processes within the container?

Also, are there examples of use in the pipeline for the repo?

Collapse
 
taillogs profile image
Ryland G

As a user you never actually interact with the container, so you can assume all steps, setup and cleanup run inside of the already initialized container. Resource cleanup is very important so that's a great question regardless. shrun automatically creates a new container before each test runs and cleans up that container after it finishes.

Also, are there examples of use in the pipeline for the repo?

Could you explain what you mean by this?

Collapse
 
hhheath profile image
Heath

Could you explain what you mean by this?

Sure! I was thinking more along the lines of a few examples of basic implementation. I see the basic demo project you've included with the post, maybe something more along those lines, showing how to implement most (if not all) features?

Thread Thread
 
taillogs profile image
Ryland G

The demo project should address exactly that. I wrote a fake CLI to showcase a full testing setup with shrun. In the README of shrun I also reference the spec file of that other repo. Do you think more is needed? I've wondered it myself and would love some more data points.

Collapse
 
mgh87 profile image
Martin Huter

Thanks for sharing your tool. I have in the coming days some gitlab pipeline scripts to refactoring and would like to give it a spin to do some TTD for cli executions.

Have you any suggestion how to set it up to test functions within a docker container that is used to run a job?

Collapse
 
taillogs profile image
Ryland G

Hey, first off thanks for taking the time to read my article and look into shrun. shrun is a great fit for TTD CLI work on paper, so I'm guessing it can be useful to you.

I don't fully understand your question about "test functions". It doesn't matter what docker image you're using, that's completely up to you. shrun has the optional flag --dockerImage which allows you to use whatever images are available locally. I actually created a repo with a fully contained example of using shrun which is available here github.com/rylandg/shrun-basic-demo. I hope this answer helps, but please let me know if it doesn't and I can help you work through whatever issues you run into.

Collapse
 
lirantal profile image
Liran Tal

That's a pretty cool idea, way to go 👏

Collapse
 
taillogs profile image
Ryland G

So glad you like the idea, thanks for the kind words.