Skip to content

Commit

Permalink
update.
Browse files Browse the repository at this point in the history
  • Loading branch information
aoli-al committed Jul 29, 2024
1 parent 012f90f commit e6c569b
Show file tree
Hide file tree
Showing 2 changed files with 41 additions and 24 deletions.
64 changes: 40 additions & 24 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,21 @@
./gradlew build
```

## Example

We provide an example application in the `integration-tests/src/main/java/example/FrayExample.java`. You may run the following command to build it:

```bash
mkdir out
javac integration-tests/src/main/java/example/FrayExample.java -d out
```

You can run the program with regular Java command
```
java -ea -cp ./out/ example.FrayExample
```
In the most cases, the program will show an `AssertionError`.

## Run Fray

### Push-button Testing
Expand All @@ -18,7 +33,7 @@ The easiest way to run Fray is to replace `java` with `fray` in your command lin
./bin/fray -cp ./out/ example.FrayExample
```

Fray will run the application with a random scheduler and print the following error:
Fray will run the application with a random scheduler. Dependening on the schedule you may either see a `DeadlockException`:

```
Error found: cmu.pasta.fray.runtime.DeadlockException
Expand Down Expand Up @@ -48,24 +63,34 @@ Stacktrace:
at example.FrayExample.run(FrayExample.java:12)
```

And you may find the recorded schedule in the `/tmp/report/` directory.

To replay a schedule, you may run the following command:

[//]: # (```bash)

[//]: # (./bin/fray -cp ./out/ example.FrayExample -scheduler replay -path /tmp/report/schedule_XXX.json)

[//]: # (```)
Or an `AssertionError`:

```
Error found: java.lang.reflect.InvocationTargetException
java.lang.reflect.InvocationTargetException
at java.base/jdk.internal.reflect.DirectMethodHandleAccessor.invoke(DirectMethodHandleAccessor.java:118)
at java.base/java.lang.reflect.Method.invoke(Method.java:580)
at cmu.pasta.fray.core.command.MethodExecutor.execute(Executor.kt:50)
at cmu.pasta.fray.core.TestRunner.run(TestRunner.kt:44)
at cmu.pasta.fray.core.MainKt.main(Main.kt:9)
Caused by: java.lang.AssertionError
at example.FrayExample.main(FrayExample.java:25)
at java.base/jdk.internal.reflect.DirectMethodHandleAccessor.invoke(DirectMethodHandleAccessor.java:103)
... 4 more
```

And you may find the recorded schedule in the `/tmp/report/` directory.

To replay a schedule, you may run the following command:

```bash
./bin/fray -cp ./out/ example.FrayExample --replay /tmp/report/schedule_0.json
```


### Application Configuration
### Customized Fray Configuration

First you need to provide a configuration file for the application you want to test. The configuration file should be in the following format:
You may also choose to provide a configuration file for the application you want to test. The configuration file should be in the following format:

```json
{
Expand Down Expand Up @@ -95,8 +120,6 @@ First you need to provide a configuration file for the application you want to t
- `max_scheduled_step`: the maximum number of scheduled steps. And Fray will throw `LivenessException` if the number of scheduled steps exceeds this value. If the value is -1, then there is no limit.


### Fray Configuration

You may use the following gradle task to run Fray:

```bash
Expand Down Expand Up @@ -124,28 +147,24 @@ Options:
-h, --help Show this message and exit
```

### Output
#### Output

The output of Fray will be saved in the `output` directory. The output directory contains the following files:

- `output.txt`: the Fray of the testing.
- `schedule_{id}.json/csv`: the schedule you can replay.

## Replay a buggy schedule
#### Replay a buggy schedule

Once Fray finds a bug as indicated in `output.txt`. You may replay it by providing the corresponding schedule.

```bash
./gradlew runFray -PconfigPath=path/to/your/application_config.json -PextraArgs="--scheduler=replay --path=path/to/schedule.json"
```

## Example

We provide an example application in the `integration-tests/src/main/java/example/FrayExample.java`. You may run the following command to test it:
#### Example

```bash
mkdir out
javac integration-tests/src/main/java/example/FrayExample.java -d out
echo '{
"executor": {
"clazz": "example.FrayExample",
Expand All @@ -162,9 +181,6 @@ echo '{
./gradlew runFray -PconfigPath="out/config.json" -PextraArgs="--iter=1000 --logger=json --scheduler=random -o=/tmp/fray-example/"
```

And you may see a failure `AssertionError` or `DeadlockException` in stdout. In `/tmp/report/`, you will see one schedule is
saved which will lead to the failure.

To replay that schedule, you may run the following command:

```bash
Expand Down
1 change: 1 addition & 0 deletions bin/fray.template
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ def main():
class_path = class_path + ":" + args.class_path
command = [
JAVA_PATH,
"-ea",
"-cp", class_path,
"-agentpath:" + JVMTI_PATH,
"-javaagent:" + AGENT_PATH,
Expand Down

0 comments on commit e6c569b

Please sign in to comment.