Skip to main content

Contribute to Stryker4s

This is the contribution guide for Stryker4s. Great to have you here! Here are a few ways you can help to make this project better.

Getting started#

To get started with developing Stryker4s, you'll need a couple of tools:

  • Java JDK, a recent version like 11 or 17 is recommended
  • sbt, to build and test the project

Once these tools are installed you can open the project with IntelliJ, or VS Code combined with Metals.

If you use VS Code with Metals, you can also install the Bloop CLI for easier compiling and testing via the command-line.

If you are have issues with setup, or want to keep a clean environment you can also use the VS Code Remote Containers feature to develop in a clean reproducible Docker container. All you need for it is VS Code, the Remote Containers extension and Docker. Then run 'Remote-Containers: Open Repository in Container...' and enter stryker-mutator/stryker4s as the repository. The devcontainer also has the Bloop and Coursier CLI tools installed.

Adding a new feature#

New features are welcome! Both as ideas or in the form of a pull request.

  1. Please create an issue with your idea first or let us know via Gitter.
  2. Create a fork on your GitHub account.
  3. When writing your code, please conform the existing coding style. We use Scalafmt as a code formatter. You can format your code by running ./bin/scalafmt, or with editor-specific settings. It also helps to take a moment to review the Scala style guide.
  4. Please create or edit unit/integration tests for any changed or added code.
  5. Confirm everything still works by running sbt test (or let the CI do the work for you).
  6. Submit the pull request!

Don't hesitate or get discouraged to get in touch! We are always happy to help you if you get stuck or have a question. Even if you don't finish something it can still be a good contribution.

Running Stryker4s on Stryker4s#

We support mutation testing Stryker4s with Stryker4s! The easiest way is to follow our guide in the root readme. If you want to test any local changes, follow these steps:

  1. Run sbt publishPluginLocal to publish a test snapshot as 0.0.0-TEST-SNAPSHOT version to your local ivy repository.
  2. Add the sbt plugin to project/plugins.sbt with 0.0.0-TEST-SNAPSHOT as the version number.
    1. If the project you are running against is not a 2.13 project, publish stryker4s-api and stryker4s-sbt-testrunner manually for your appropriate version (.e.g. sbt "stryker4s-api2_11/publishLocal; stryker4s-sbt-testrunner2_11/publishLocal")
  3. Run stryker4s as described in the readme.

Learning resources#

Here are some resources you can use if you are new to mutation testing:

Mutation switching#

Stryker4s uses a technique called 'mutation switching' to perform mutations. It does this by adding all mutations into a single pattern match, and activating the correct mutation via an environment variable. This would change the following code:

def isAdult(person: Person) = {  person.age >= 18}

To:

def isAdult(person: Person) = {  sys.env.get("ACTIVE_MUTATION") match {    case Some("1") => person.age > 18    case Some("2") => person.age < 18    case Some("3") => person.age == 18    case _         => person.age >= 18 // Original  }}

The effect is the same as compiling each mutation seperately, but instead we only have to do it once. This is a big performance improvement, but does mean we have to be more careful about compile errors. Read more about mutation switching on our blog

Community#

Want to help in some other ways? Great! Here are some things you could do:

  • Evangelize mutation testing
    • Mutation testing is still relatively new, especially in Scala. Please help us get the word out there!
    • Share your stories in blog posts and on social media. And please let us know about it!
  • Did you use Stryker4s? Your feedback is very valuable to us. Both good and bad! Please contact us to let us know what you think.