more documentation for Docker and better logs

WebFuzzing · Dec 12, 2024 · cff3b35 · cff3b35
1 parent 2e48ab8
commit cff3b35
Show file tree

Hide file tree

Showing 6 changed files with 72 additions and 17 deletions.
diff --git a/Dockerfile b/Dockerfile
@@ -25,10 +25,11 @@ ENTRYPOINT [  \
 # Example local BB
 # docker run -v "/$(pwd)/generated_tests":/generated_tests  webfuzzing/evomaster  --blackBox true --bbSwaggerUrl http://host.docker.internal:8080/v3/api-docs --maxTime 5s
 #
-# Example WB
+# Example WB  (NOT IMPLEMENTED YET)
 # docker run -v "/$(pwd)/generated_tests":/generated_tests  webfuzzing/evomaster --dockerLocalhost true
 #
-# TODO and em.yaml
+# Setting for existing em.yaml
+# -v "/$(pwd)/em.yaml":/em.yaml
 #
 # Debugging
 # docker run -it --entrypoint sh  webfuzzing/evomaster

diff --git a/core/src/main/kotlin/org/evomaster/core/EMConfig.kt b/core/src/main/kotlin/org/evomaster/core/EMConfig.kt
@@ -1073,10 +1073,6 @@ class EMConfig {
     @Max(maxTcpPort)
     var sutControllerPort = ControllerConstants.DEFAULT_CONTROLLER_PORT
 
-    @Important(6.2)
-    @Cfg("Replace references to 'localhost' to point to the actual host machine." +
-            " Only needed when running EvoMaster inside Docker.")
-    var dockerLocalhost = false
 
     @Important(7.0)
     @Url
@@ -1090,6 +1086,17 @@ class EMConfig {
             " Users should not modify this parameter, as it is set automatically in the Docker image of EvoMaster.")
     var runningInDocker = false
 
+    /**
+     * TODO this is currently not implemented.
+     * Even if did, there would still be major issues with handling WireMock.
+     * Until we can think of a good solution there, no point in implementing this.
+     */
+    @Experimental
+    @Cfg("Replace references to 'localhost' to point to the actual host machine." +
+            " Only needed when running EvoMaster inside Docker.")
+    var dockerLocalhost = false
+
+
     @FilePath
     @Cfg("When generating tests in JavaScript, there is the need to know where the driver is located in respect to" +
             " the generated tests")

diff --git a/core/src/main/kotlin/org/evomaster/core/Main.kt b/core/src/main/kotlin/org/evomaster/core/Main.kt
@@ -87,14 +87,25 @@ class Main {
                 val config = EMConfig().apply { updateProperties(options) }
 
                 if(config.runningInDocker){
-                    LoggingUtil.getInfoLogger().info("You are running EvoMaster inside Docker." +
-                            " To access the generated test suite under '/generated_tests', you will need to mount a folder" +
-                            " or volume." +
-                            " Also references to host machine on 'localhost' would need to be replaced with" +
-                            " 'host.docker.internal'." +
-                            " If this is the first time you run EvoMaster in Docker, you are strongly recommended to first" +
-                            " check the documentation at:" +
-                            " ${inBlue("https://github.com/WebFuzzing/EvoMaster/blob/master/docs/docker.md")}")
+                    if(config.blackBox) {
+                        LoggingUtil.getInfoLogger().info(
+                            inGreen("You are running EvoMaster inside Docker." +
+                                    " To access the generated test suite under '/generated_tests', you will need to mount a folder" +
+                                    " or volume." +
+                                    " Also references to host machine on 'localhost' would need to be replaced with" +
+                                    " 'host.docker.internal'." +
+                                    " If this is the first time you run EvoMaster in Docker, you are strongly recommended to first" +
+                                    " check the documentation at:") +
+                                    " ${inBlue("https://github.com/WebFuzzing/EvoMaster/blob/master/docs/docker.md")}"
+                        )
+                    } else {
+                        LoggingUtil.getInfoLogger().warn(
+                            inYellow(
+                            "White-box testing (default in EvoMaster) is currently not supported / not recommended in Docker." +
+                                    " To run EvoMaster in black-box mode, you can use --blackBox true."
+                            )
+                        )
+                    }
                 }
 
                 initAndRun(args)

diff --git a/docs/config_file.md b/docs/config_file.md
@@ -0,0 +1,3 @@
+## Config
+
+<mark>Documentation under construction</mark>
diff --git a/docs/docker.md b/docs/docker.md
@@ -6,7 +6,13 @@ It can be run with:
 
 > docker run webfuzzing/evomaster  \<options\>
 
-Where `<options>` would be the [command-line options](options.md).
+Where `<options>` would be the [command-line options](options.md), 
+like for example `--blackBox true`
+
+> __IMPORTANT__
+>
+> For __white-box__ testing, running from Docker is currently not supported. As such, it is discouraged.
+> You can try it, but likely you will get major issues with hostname and ephemeral port resolutions, as well as issues with external dependency mocks.
 
 
 ## Accessing the generated test files
@@ -19,6 +25,10 @@ An example is mounting the local `./generated_tests`, using for example:
 
 There can be other ways to access the `/generated_tests` folder inside the Docker image (e.g., using volumes), but, for that, you will need to check the Docker documentation.  
 
+WARNING: note the `/` before `$(pwd)`. This is needed only if running in a MSYS shell on Windows like _Git Bash_, as it automatically converts paths on the command line. 
+Unfortunately, this will also mess up any input parameter to EvoMaster that is recognized as a path (e.g., if starting with a `/`).
+You can [read more here](https://stackoverflow.com/questions/52944738/how-to-force-git-for-windows-bash-shell-to-not-convert-path-string-to-windows-p).
+
 ## Issues with "localhost" 
 
 An important fact to keep in mind is that references to `localhost` will point to the Docker virtual network, and not your host machine.
@@ -35,6 +45,7 @@ would need to be replaced with
 
 Note that here the port `8080` and the the path `/v3/api-docs` are just examples.
 
+<!--
 An equivalent solution is to use the option
 
 > --dockerLocalhost true
@@ -44,7 +55,13 @@ i.e.,
 > --bbSwaggerUrl http://localhost:8080/v3/api-docs --dockerLocalhost true
 
 This can be useful if you do not remember or do not want to copy&paste the hostname `host.docker.internal`.
+-->
+
+
+
+
 
+<!--
 For __white-box__ testing, by default _EvoMaster_ core tool process will try to connect to a driver, listening on `localhost`. 
 This will not directly work in Docker.
 Such default configuration can be changed with the option:
@@ -63,7 +80,23 @@ This way, you can run __white-box__ _EvoMaster_ by using for example:
 
 > docker run -v "/$(pwd)/generated_tests":/generated_tests  webfuzzing/evomaster --dockerLocalhost true
 
+-->
 
 ## Handling "em.yaml" configuration file
 
-TODO
+If you want to use a configuration file (e.g., `em.yaml`) to specify command-line options, this needs to be mounted into Docker.
+For example by using:
+
+> -v "$(pwd)/em.yaml":/em.yaml
+
+By default, _EvoMaster_ in Docker searches for a configuration file under `/em.yaml`. 
+You can mount your configuration file (based on its absolute path) into that. 
+
+> WARNING: in _Git Bash_, you will need a `/` before `$(pwd)`, i.e., Linux-like paths should start with a `//` and not a `/` (as otherwise get converted, and you might end up seeing weird things like prepended paths such as `C:/Program Files/Git`). Also, options like 
+`--configPath` will not work there. 
+
+
+By default, if there is no `em.yaml` file, _EvoMaster_ will create one in the current working directory, with comments on how it should be configured. 
+However, if you run through Docker, you will not be able to directly access such file, unless you mount the whole `/` root folder (which is not recommended). 
+But you can still create it manually. 
+[See documentation](config_file.md).
diff --git a/docs/options.md b/docs/options.md
@@ -53,7 +53,6 @@ There are 3 types of options:
 |`endpointTagFilter`| __String__. Comma-separated list of OpenAPI/Swagger 'tags' definitions. Only the REST endpoints having at least one of such tags will be fuzzed. If no tag is specified here, then such filter is not applied. *Default value*: `null`.|
 |`sutControllerHost`| __String__. Host name or IP address of where the SUT EvoMaster Controller Driver is listening on. This option is only needed for white-box testing. *Default value*: `localhost`.|
 |`sutControllerPort`| __Int__. TCP port of where the SUT EvoMaster Controller Driver is listening on. This option is only needed for white-box testing. *Constraints*: `min=0.0, max=65535.0`. *Default value*: `40100`.|
-|`dockerLocalhost`| __Boolean__. Replace references to 'localhost' to point to the actual host machine. Only needed when running EvoMaster inside Docker. *Default value*: `false`.|
 |`overrideOpenAPIUrl`| __String__. If specified, override the OpenAPI URL location given by the EvoMaster Driver. This option is only needed for white-box testing. *Constraints*: `URL`. *Default value*: `""`.|
 
 ## Internal Command-Line Options
@@ -228,6 +227,7 @@ There are 3 types of options:
 |`appendToTargetHeuristicsFile`| __Boolean__. Whether should add to an existing target heuristics file, instead of replacing it. It is only used when processFormat is TARGET_HEURISTIC. *Default value*: `false`.|
 |`bbProbabilityUseDataPool`| __Double__. Specify the probability of using the data pool when sampling test cases. This is for black-box (bb) mode. *Constraints*: `probability 0.0-1.0`. *Default value*: `0.8`.|
 |`discoveredInfoRewardedInFitness`| __Boolean__. If there is new discovered information from a test execution, reward it in the fitness function. *Default value*: `false`.|
+|`dockerLocalhost`| __Boolean__. Replace references to 'localhost' to point to the actual host machine. Only needed when running EvoMaster inside Docker. *Default value*: `false`.|
 |`dpcTargetTestSize`| __Int__. Specify a max size of a test to be targeted when either DPC_INCREASING or DPC_DECREASING is enabled. *Default value*: `1`.|
 |`employResourceSizeHandlingStrategy`| __Enum__. Specify a strategy to determinate a number of resources to be manipulated throughout the search. *Valid values*: `NONE, RANDOM, DPC`. *Default value*: `NONE`.|
 |`enableAdaptiveResourceStructureMutation`| __Boolean__. Specify whether to decide the resource-based structure mutator and resource to be mutated adaptively based on impacts during focused search.Note that it only works when resource-based solution is enabled for solving REST problem. *Default value*: `false`.|
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		## Config

		<mark>Documentation under construction</mark>