<commit_before>scala-collections-laws
======================

Partially automatic generation of tests for the Scala collections library.

### Warning

The Stream test will not complete unless you use a version of Scala with SI-6827 patched.  If your normal scala isn't that up to date, use --scala= when running tests to get a version with the fixed library.

## How to use

To generate the tests, `make`

To generate and run the tests, `make run`

To generate, recompile even tests whose source hasn't changed, and run, `make full`

To generate and compile but don't run tests, `make build`

To generate all the tests but run only the ones that have changed, `make quick`

By default, it uses three threads at a time to compile/run (`--run=3`).  This can be altered in the makefile.
 
If you want to only run tests that have been modified and therefore probably need to be recompiled, use `--changed` (`make quick` uses this)

If you want to only compile and not run anything (messages will assume all runs succeed), use `--compile-only` (`make build` uses this)
 
If you want to recompile everything whether or not the source was changed on this run, use `--recompile` (`make full` uses this)
 
To specify what command to use for the compiler, use `--scalac=fsc` or somesuch (paths are okay; be sure to escape spaces).
 
To specify what command to use to run, use `--scala=scala` or somesuch.
 
To specify arguments, use `--scala-args=arg1` `--scala-args=arg2` etc. (one `--scalac-args=` per argument).

`Laws.scala` will create and compile `Instances.scala`, and will create a whole bunch of source in `generated-tests` and class files in `tests/generated/collection` (be warned).

### A mini-walkthrough of detecting failed tests and verifying a bug

If we execute a freshly cloned copy:

```bash
git clone https://github.com/Ichoran/scala-collections-laws
cd scala-collections-laws
make run
```

we should see something like the following (`...` indicates many more output lines, not a literal output string from the tests):

```<commit_msg>Docs updated for sbt version.<commit_after>scala-collections-laws
======================

Partially automatic generation of tests for the Scala collections library.

### Warning

The Stream test will not complete unless you use a version of Scala with SI-6827 patched.

## Usage

The collections tests now are a sbt project.

From the root directory you should be able to compile everything with

```bash
sbt -mem 4096 tests/compile
```

which will compile and run the sub-projects `laws` and `inst`, generate all the tests, and compile them.

(This will take about 12 minutes, though exactly how long will depend on the machine.)

You can then run the tests with

```bash
sbt -mem 4096 "tests/runMain tests.generated.collection.Test_All"
```

which will take about two minutes and state something not so terribly helpful like

```
1 errors
100 successful
```

when it is done.  (This will be improved, obviously, to give useful information about errors, if any.)

## How to use the non-current non-sbt branch (historical)

To generate the tests, `make`

To generate and run the tests, `make run`

To generate, recompile even tests whose source hasn't changed, and run, `make full`

To generate and compile but don't run tests, `make build`

To generate all the tests but run only the ones that have changed, `make quick`

By default, it uses three threads at a time to compile/run (`--run=3`).  This can be altered in the makefile.
 
If you want to only run tests that have been modified and therefore probably need to be recompiled, use `--changed` (`make quick` uses this)

If you want to only compile and not run anything (messages will assume all runs succeed), use `--compile-only` (`make build` uses this)
 
If you want to recompile everything whether or not the source was changed on this run, use `--recompile` (`make full` uses this)
 
To specify what command to use for the compiler, use `--scalac=fsc` or somesuch (paths are okay; be sure to escape spaces).
 
To specify what command to use to run, use `--scala=scala` or somesuch.
 
To specify arguments, use `--scala-args=arg1` `--scala-args=arg2` etc. (one `--scalac-args=` per argument).

`Laws.scala` will create and compile `Instances.scala`, and will create a whole bunch of source in `generated-tests` and class files in `tests/generated/collection` (be warned).

### A mini-walkthrough of detecting failed tests and verifying a bug (non-sbt branch, historical)

If we execute a freshly cloned copy:

```bash
git clone https://github.com/Ichoran/scala-collections-laws
cd scala-collections-laws
make run
```

we should see something like the following (`...` indicates many more output lines, not a literal output string from the tests):

```
{'fraction_non_alphanumeric': 0.09121479613282892, 'fraction_numerical': 0.0058848255569567045, 'mean_word_length': 4.201092896174863, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3124164', 'n_tokens_mistral': 1377, 'n_tokens_neox': 1276, 'n_words': 702}