make it clearer that you need to pass a filename to the various profile flags, not an absolute directory

Author: onsi

docs/index.md

@@ -3745,7 +3745,7 @@ You can also specify the `--covermode` to be one of `set` ("was this code called
 
 When run with `--cover`, Ginkgo will generate a single `coverprofile.out` file that captures the coverage statistics of all the suites that ran.  You can change the name of this file by specifying `-coverprofile=filename`.  If you would like to keep separate coverprofiles for each suite use the `--keep-separate-coverprofiles` option.
 
-Ginkgo also honors the `--output-dir` flag when generating coverprofiles.  If you specify `--output-dir` the generated coverprofile will be placed in the requested directory.  If you also specify `--keep-separate-coverprofiles` individual package coverprofiles will be placed in the requested directory and namespaced with a prefix that contains the name of the package in question.
+Note that `-coverprofile` only takes a filename, not a path.  To place the coverprofile in a particular path you should specify `--output-dir` the generated coverprofile will be placed in the requested directory.  If you also specify `--keep-separate-coverprofiles` individual package coverprofiles will be placed in the requested directory and namespaced with a prefix that contains the name of the package in question.
 
 Finally, when running a suite that has [programmatically focused specs](#focused-specs) (i.e. specs with the `Focus` decorator or with nodes prefixed with an `F`) Ginkgo exits the suite early with a non-zero exit code.  This interferes with `go test`'s profiling code and prevents profiles from being generated.  Ginkgo will tell you this has happened.  If you want to profile just a subset of your suite you'll need to use a different [mechanism](#filtering-specs) to filter your specs.
 

integration/profiling_test.go

@@ -141,6 +141,12 @@ var _ = Describe("Profiling Specs", func() {
 				Ω(fm.PathTo("coverage", "myprofile.out")).Should(BeAnExistingFile())
 				Ω(fm.PathTo("coverage", "coverprofile.out")).ShouldNot(BeAnExistingFile())
 			})
+
+			It("fails if the cover profile is not just a filename", func() {
+				session := startGinkgo(fm.PathTo("coverage"), "--no-color", "-coverprofile=/path/to/profile.out")
+				Eventually(session).Should(gexec.Exit(1))
+				Ω(session.Err).Should(gbytes.Say(`--coverprofile expects a filename but was given a path: /path/to/profile.out`))
+			})
 		})
 
 		Context("when multiple suites are tested", func() {

types/config.go

@@ -257,8 +257,12 @@ var FlagSections = GinkgoFlagSections{
 	{Key: "filter", Style: "{{cyan}}", Heading: "Filtering Tests"},
 	{Key: "failure", Style: "{{red}}", Heading: "Failure Handling"},
 	{Key: "output", Style: "{{magenta}}", Heading: "Controlling Output Formatting"},
-	{Key: "code-and-coverage-analysis", Style: "{{orange}}", Heading: "Code and Coverage Analysis"},
-	{Key: "performance-analysis", Style: "{{coral}}", Heading: "Performance Analysis"},
+	{Key: "code-and-coverage-analysis", Style: "{{orange}}", Heading: "Code and Coverage Analysis",
+		Description: "When generating a cover files, please pass a filename {{bold}}not{{/}} a path.  To specify a different directory use {{magenta}}--output-dir{{/}}.",
+	},
+	{Key: "performance-analysis", Style: "{{coral}}", Heading: "Performance Analysis",
+		Description: "When generating profile files, please pass filenames {{bold}}not{{/}} a path.  Ginkgo will generate a profile file with the given name in the package's directory.  To specify a different directory use {{magenta}}--output-dir{{/}}.",
+	},
 	{Key: "debug", Style: "{{blue}}", Heading: "Debugging Tests",
 		Description: "In addition to these flags, Ginkgo supports a few debugging environment variables.  To change the parallel server protocol set {{blue}}GINKGO_PARALLEL_PROTOCOL{{/}} to {{bold}}HTTP{{/}}.  To avoid pruning callstacks set {{blue}}GINKGO_PRUNE_STACK{{/}} to {{bold}}FALSE{{/}}."},
 	{Key: "watch", Style: "{{light-yellow}}", Heading: "Controlling Ginkgo Watch"},
@@ -572,7 +576,7 @@ var GoBuildFlags = GinkgoFlags{
 // GoRunFlags provides flags for the Ginkgo CLI  run, and watch commands that capture go's run-time flags.  These are passed to the compiled test binary by the ginkgo CLI
 var GoRunFlags = GinkgoFlags{
 	{KeyPath: "Go.CoverProfile", Name: "coverprofile", UsageArgument: "file", SectionKey: "code-and-coverage-analysis",
-		Usage: `Write a coverage profile to the file after all tests have passed. Sets -cover.`},
+		Usage: `Write a coverage profile to the file after all tests have passed. Sets -cover.  Must be passed a filename, not a path.  Use output-dir to control the location of the output.`},
 	{KeyPath: "Go.BlockProfile", Name: "blockprofile", UsageArgument: "file", SectionKey: "performance-analysis",
 		Usage: `Write a goroutine blocking profile to the specified file when all tests are complete. Preserves test binary.`},
 	{KeyPath: "Go.BlockProfileRate", Name: "blockprofilerate", UsageArgument: "rate", SectionKey: "performance-analysis",
@@ -600,6 +604,22 @@ func VetAndInitializeCLIAndGoConfig(cliConfig CLIConfig, goFlagsConfig GoFlagsCo
 		errors = append(errors, GinkgoErrors.BothRepeatAndUntilItFails())
 	}
 
+	if strings.ContainsRune(goFlagsConfig.CoverProfile, os.PathSeparator) {
+		errors = append(errors, GinkgoErrors.ExpectFilenameNotPath("--coverprofile", goFlagsConfig.CoverProfile))
+	}
+	if strings.ContainsRune(goFlagsConfig.CPUProfile, os.PathSeparator) {
+		errors = append(errors, GinkgoErrors.ExpectFilenameNotPath("--cpuprofile", goFlagsConfig.CPUProfile))
+	}
+	if strings.ContainsRune(goFlagsConfig.MemProfile, os.PathSeparator) {
+		errors = append(errors, GinkgoErrors.ExpectFilenameNotPath("--memprofile", goFlagsConfig.MemProfile))
+	}
+	if strings.ContainsRune(goFlagsConfig.BlockProfile, os.PathSeparator) {
+		errors = append(errors, GinkgoErrors.ExpectFilenameNotPath("--blockprofile", goFlagsConfig.BlockProfile))
+	}
+	if strings.ContainsRune(goFlagsConfig.MutexProfile, os.PathSeparator) {
+		errors = append(errors, GinkgoErrors.ExpectFilenameNotPath("--mutexprofile", goFlagsConfig.MutexProfile))
+	}
+
 	//initialize the output directory
 	if cliConfig.OutputDir != "" {
 		err := os.MkdirAll(cliConfig.OutputDir, 0777)

types/errors.go

@@ -629,6 +629,13 @@ func (g ginkgoErrors) BothRepeatAndUntilItFails() error {
 	}
 }
 
+func (g ginkgoErrors) ExpectFilenameNotPath(flag string, path string) error {
+	return GinkgoError{
+		Heading: fmt.Sprintf("%s expects a filename but was given a path: %s", flag, path),
+		Message: fmt.Sprintf("%s takes a filename, not a path.  Use --output-dir to specify a directory to collect all test outputs.", flag),
+	}
+}
+
 /* Stack-Trace parsing errors */
 
 func (g ginkgoErrors) FailedToParseStackTrace(message string) error {