"use strict";(self.webpackChunkpantsbuild_org=self.webpackChunkpantsbuild_org||[]).push([[226990],{854069:(e,t,r)=>{r.r(t),r.d(t,{assets:()=>a,contentTitle:()=>l,default:()=>_,frontMatter:()=>c,metadata:()=>d,toc:()=>h});var o=r(474848),s=r(28453),n=r(142519),i=r(87598);const c={title:"go-test",description:"Options for Go tests.\n"},l=void 0,d={id:"reference/subsystems/go-test",title:"go-test",description:"Options for Go tests.\n",source:"@site/versioned_docs/version-2.25/reference/subsystems/go-test.mdx",sourceDirName:"reference/subsystems",slug:"/reference/subsystems/go-test",permalink:"/stable/reference/subsystems/go-test",draft:!1,unlisted:!1,tags:[],version:"2.25",frontMatter:{title:"go-test",description:"Options for Go tests.\n"},sidebar:"referenceSidebar",previous:{title:"flake8",permalink:"/stable/reference/subsystems/flake8"},next:{title:"go-vet",permalink:"/stable/reference/subsystems/go-vet"}},a={},h=[{value:"Basic options",id:"basic-options",level:2},{value:"<code>args</code>",id:"args",level:3},{value:"<code>block_profile</code>",id:"block_profile",level:3},{value:"<code>cover_mode</code>",id:"cover_mode",level:3},{value:"<code>coverage_html</code>",id:"coverage_html",level:3},{value:"<code>coverage_packages</code>",id:"coverage_packages",level:3},{value:"<code>cpu_profile</code>",id:"cpu_profile",level:3},{value:"<code>force_asan</code>",id:"force_asan",level:3},{value:"<code>force_msan</code>",id:"force_msan",level:3},{value:"<code>force_race</code>",id:"force_race",level:3},{value:"<code>mem_profile</code>",id:"mem_profile",level:3},{value:"<code>mutex_profile</code>",id:"mutex_profile",level:3},{value:"<code>skip</code>",id:"skip",level:3},{value:"<code>trace</code>",id:"trace",level:3},{value:"Advanced options",id:"advanced-options",level:2},{value:"<code>coverage_output_dir</code>",id:"coverage_output_dir",level:3},{value:"<code>output_test_binary</code>",id:"output_test_binary",level:3},{value:"Deprecated options",id:"deprecated-options",level:2},{value:"Related subsystems",id:"related-subsystems",level:2}];function p(e){const t={a:"a",code:"code",h2:"h2",h3:"h3",hr:"hr",li:"li",p:"p",ul:"ul",...(0,s.R)(),...e.components};return(0,o.jsxs)(o.Fragment,{children:[(0,o.jsx)(t.hr,{}),"\n",(0,o.jsx)(t.p,{children:"Options for Go tests."}),"\n",(0,o.jsxs)(t.p,{children:["Backend: ",(0,o.jsx)("span",{className:"color--primary",children:(0,o.jsx)(t.code,{children:"pants.backend.experimental.go.lint.vet"})})]}),"\n",(0,o.jsxs)(t.p,{children:["Config section: ",(0,o.jsx)("span",{className:"color--primary",children:(0,o.jsx)(t.code,{children:"[go-test]"})})]}),"\n",(0,o.jsxs)("span",{className:i.A.options,children:[(0,o.jsx)(t.h2,{id:"basic-options",children:"Basic options"}),(0,o.jsx)(t.h3,{id:"args",children:(0,o.jsx)(t.code,{children:"args"})}),(0,o.jsxs)(n.A,{cli_repr:'--go-test-args="[<shell_str>, <shell_str>, ...]", ... -- [<shell_str> [<shell_str> [...]]]',env_repr:"PANTS_GO_TEST_ARGS",toml_repr:"[go-test]\nargs = [\n    <shell_str>,\n    <shell_str>,\n    ...,\n]",default_repr:"[]",children:[(0,o.jsxs)(t.p,{children:["Arguments to pass directly to Go test binary, e.g. ",(0,o.jsx)(t.code,{children:"--go-test-args='-run TestFoo -v'"}),"."]}),(0,o.jsxs)(t.p,{children:["Known Go test options will be transformed into the form expected by the test binary, e.g. ",(0,o.jsx)(t.code,{children:"-v"})," becomes ",(0,o.jsx)(t.code,{children:"-test.v"}),". Run ",(0,o.jsx)(t.code,{children:"go help testflag"})," from the Go SDK to learn more about the options supported by Go test binaries."]})]}),(0,o.jsx)(t.h3,{id:"block_profile",children:(0,o.jsx)(t.code,{children:"block_profile"})}),(0,o.jsx)(n.A,{cli_repr:"--[no-]go-test-block-profile",env_repr:"PANTS_GO_TEST_BLOCK_PROFILE",toml_repr:"[go-test]\nblock_profile = <bool>",default_repr:"False",children:(0,o.jsxs)(t.p,{children:["Capture a goroutine blocking profile from the execution of the test runner. The profile will be written to the file ",(0,o.jsx)(t.code,{children:"block.out"})," in the test extra output directory. The test binary will also be written to the test extra output directory."]})}),(0,o.jsx)(t.h3,{id:"cover_mode",children:(0,o.jsx)(t.code,{children:"cover_mode"})}),(0,o.jsxs)(n.A,{cli_repr:"--go-test-cover-mode=<GoCoverMode>",env_repr:"PANTS_GO_TEST_COVER_MODE",toml_repr:"[go-test]\ncover_mode = <GoCoverMode>",one_of:"set, count, atomic",default_repr:"set",children:[(0,o.jsxs)(t.p,{children:["Coverage mode to use when running Go tests with coverage analysis enabled via ",(0,o.jsx)(t.code,{children:"--test-use-coverage"}),". Valid values are ",(0,o.jsx)(t.code,{children:"set"}),", ",(0,o.jsx)(t.code,{children:"count"}),", and ",(0,o.jsx)(t.code,{children:"atomic"}),":"]}),(0,o.jsxs)(t.ul,{children:["\n",(0,o.jsxs)(t.li,{children:[(0,o.jsx)(t.code,{children:"set"}),": bool: does this statement run?"]}),"\n",(0,o.jsxs)(t.li,{children:[(0,o.jsx)(t.code,{children:"count"}),": int: how many times does this statement run?"]}),"\n",(0,o.jsxs)(t.li,{children:[(0,o.jsx)(t.code,{children:"atomic"}),": int: count, but correct in multithreaded tests; significantly more expensive."]}),"\n"]})]}),(0,o.jsx)(t.h3,{id:"coverage_html",children:(0,o.jsx)(t.code,{children:"coverage_html"})}),(0,o.jsx)(n.A,{cli_repr:"--[no-]go-test-coverage-html",env_repr:"PANTS_GO_TEST_COVERAGE_HTML",toml_repr:"[go-test]\ncoverage_html = <bool>",default_repr:"True",children:(0,o.jsxs)(t.p,{children:["If true, then convert coverage reports to HTML format and write a ",(0,o.jsx)(t.code,{children:"coverage.html"})," file next to the raw coverage data."]})}),(0,o.jsx)(t.h3,{id:"coverage_packages",children:(0,o.jsx)(t.code,{children:"coverage_packages"})}),(0,o.jsxs)(n.A,{cli_repr:"--go-test-coverage-packages=\"['<str>', '<str>', ...]\"",env_repr:"PANTS_GO_TEST_COVERAGE_PACKAGES",toml_repr:"[go-test]\ncoverage_packages = [\n    '<str>',\n    '<str>',\n    ...,\n]",default_repr:"[]",children:[(0,o.jsx)(t.p,{children:'A list of "import path patterns" for determining which import paths will be instrumented for code coverage.'}),(0,o.jsxs)(t.p,{children:["From ",(0,o.jsx)(t.code,{children:"go help packages"}),":"]}),(0,o.jsx)(t.p,{children:'An import path is a pattern if it includes one or more "..." wildcards, each of which can match any string, including the empty string and strings containing slashes. Such a pattern expands to all package directories found in the GOPATH trees with names matching the patterns.'}),(0,o.jsx)(t.p,{children:'To make common patterns more convenient, there are two special cases. First, /... at the end of the pattern can match an empty string, so that net/... matches both net and packages in its subdirectories, like net/http. Second, any slash-separated pattern element containing a wildcard never participates in a match of the "vendor" element in the path of a vendored package, so that ./... does not match packages in subdirectories of ./vendor or ./mycode/vendor, but ./vendor/... and ./mycode/vendor/... do. Note, however, that a directory named vendor that itself contains code is not a vendored package: cmd/vendor would be a command named vendor, and the pattern cmd/... matches it. See golang.org/s/go15vendor for more about vendoring.'}),(0,o.jsxs)(t.p,{children:["This option is similar to the ",(0,o.jsx)(t.code,{children:"go test -coverpkg"})," option, but without support currently for reserved import path patterns like ",(0,o.jsx)(t.code,{children:"std"})," and ",(0,o.jsx)(t.code,{children:"all"}),"."]})]}),(0,o.jsx)(t.h3,{id:"cpu_profile",children:(0,o.jsx)(t.code,{children:"cpu_profile"})}),(0,o.jsx)(n.A,{cli_repr:"--[no-]go-test-cpu-profile",env_repr:"PANTS_GO_TEST_CPU_PROFILE",toml_repr:"[go-test]\ncpu_profile = <bool>",default_repr:"False",children:(0,o.jsxs)(t.p,{children:["Capture a CPU profile from the execution of the test runner. The profile will be written to the file ",(0,o.jsx)(t.code,{children:"cpu.out"})," in the test extra output directory. The test binary will also be written to the test extra output directory."]})}),(0,o.jsx)(t.h3,{id:"force_asan",children:(0,o.jsx)(t.code,{children:"force_asan"})}),(0,o.jsxs)(n.A,{cli_repr:"--[no-]go-test-force-asan",env_repr:"PANTS_GO_TEST_FORCE_ASAN",toml_repr:"[go-test]\nforce_asan = <bool>",default_repr:"False",children:[(0,o.jsxs)(t.p,{children:['If true, then always enable interoperation between Go and the C/C++ "address sanitizer" when running tests regardless of the test-by-test ',(0,o.jsx)(t.code,{children:"asan"})," field on the relevant ",(0,o.jsx)(t.code,{children:"go_package"})," target."]}),(0,o.jsxs)(t.p,{children:["See ",(0,o.jsx)(t.a,{href:"https://github.com/google/sanitizers/wiki/AddressSanitizer",children:"https://github.com/google/sanitizers/wiki/AddressSanitizer"})," for additional information about the C/C++ address sanitizer."]})]}),(0,o.jsx)(t.h3,{id:"force_msan",children:(0,o.jsx)(t.code,{children:"force_msan"})}),(0,o.jsxs)(n.A,{cli_repr:"--[no-]go-test-force-msan",env_repr:"PANTS_GO_TEST_FORCE_MSAN",toml_repr:"[go-test]\nforce_msan = <bool>",default_repr:"False",children:[(0,o.jsxs)(t.p,{children:['If true, then always enable interoperation between Go and the C/C++ "memory sanitizer" when running tests regardless of the test-by-test ',(0,o.jsx)(t.code,{children:"msan"})," field on the relevant ",(0,o.jsx)(t.code,{children:"go_package"})," target."]}),(0,o.jsxs)(t.p,{children:["See ",(0,o.jsx)(t.a,{href:"https://github.com/google/sanitizers/wiki/MemorySanitizer",children:"https://github.com/google/sanitizers/wiki/MemorySanitizer"})," for additional information about the C/C++ memory sanitizer."]})]}),(0,o.jsx)(t.h3,{id:"force_race",children:(0,o.jsx)(t.code,{children:"force_race"})}),(0,o.jsxs)(n.A,{cli_repr:"--[no-]go-test-force-race",env_repr:"PANTS_GO_TEST_FORCE_RACE",toml_repr:"[go-test]\nforce_race = <bool>",default_repr:"False",children:[(0,o.jsxs)(t.p,{children:["If true, then always enable the Go data race detector when running tests regardless of the test-by-test ",(0,o.jsx)(t.code,{children:"test_race"})," field on the relevant ",(0,o.jsx)(t.code,{children:"go_package"})," target."]}),(0,o.jsxs)(t.p,{children:["See ",(0,o.jsx)(t.a,{href:"https://go.dev/doc/articles/race_detector",children:"https://go.dev/doc/articles/race_detector"})," for additional information about the Go data race detector."]})]}),(0,o.jsx)(t.h3,{id:"mem_profile",children:(0,o.jsx)(t.code,{children:"mem_profile"})}),(0,o.jsx)(n.A,{cli_repr:"--[no-]go-test-mem-profile",env_repr:"PANTS_GO_TEST_MEM_PROFILE",toml_repr:"[go-test]\nmem_profile = <bool>",default_repr:"False",children:(0,o.jsxs)(t.p,{children:["Capture an allocation profile from the execution of the test runner after tests have passed. The profile will be written to the file ",(0,o.jsx)(t.code,{children:"mem.out"})," in the test extra output directory. The test binary will also be written to the test extra output directory."]})}),(0,o.jsx)(t.h3,{id:"mutex_profile",children:(0,o.jsx)(t.code,{children:"mutex_profile"})}),(0,o.jsx)(n.A,{cli_repr:"--[no-]go-test-mutex-profile",env_repr:"PANTS_GO_TEST_MUTEX_PROFILE",toml_repr:"[go-test]\nmutex_profile = <bool>",default_repr:"False",children:(0,o.jsxs)(t.p,{children:["Capture a mutex contention profile from the execution of the test runner when all tests are complete. The profile will be written to the file ",(0,o.jsx)(t.code,{children:"mutex.out"})," in the test extra output directory. The test binary will also be written to the test extra output directory."]})}),(0,o.jsx)(t.h3,{id:"skip",children:(0,o.jsx)(t.code,{children:"skip"})}),(0,o.jsx)(n.A,{cli_repr:"--[no-]go-test-skip",env_repr:"PANTS_GO_TEST_SKIP",toml_repr:"[go-test]\nskip = <bool>",default_repr:"False",children:(0,o.jsxs)(t.p,{children:["If true, don't use Go test binary when running ",(0,o.jsx)(t.code,{children:"pants test"}),"."]})}),(0,o.jsx)(t.h3,{id:"trace",children:(0,o.jsx)(t.code,{children:"trace"})}),(0,o.jsx)(n.A,{cli_repr:"--[no-]go-test-trace",env_repr:"PANTS_GO_TEST_TRACE",toml_repr:"[go-test]\ntrace = <bool>",default_repr:"False",children:(0,o.jsxs)(t.p,{children:["Capture an execution trace from the execution of the test runner. The trace will be written to the file ",(0,o.jsx)(t.code,{children:"trace.out"})," in the test extra output directory."]})}),(0,o.jsx)(t.h2,{id:"advanced-options",children:"Advanced options"}),(0,o.jsx)(t.h3,{id:"coverage_output_dir",children:(0,o.jsx)(t.code,{children:"coverage_output_dir"})}),(0,o.jsxs)(n.A,{cli_repr:"--go-test-coverage-output-dir=<str>",env_repr:"PANTS_GO_TEST_COVERAGE_OUTPUT_DIR",toml_repr:"[go-test]\ncoverage_output_dir = <str>",default_repr:"{distdir}/coverage/go/{target_spec}",children:[(0,o.jsx)(t.p,{children:"Path to write the Go coverage reports to. Must be relative to the build root."}),(0,o.jsx)(t.p,{children:"Replacements:"}),(0,o.jsxs)(t.ul,{children:["\n",(0,o.jsxs)(t.li,{children:[(0,o.jsx)(t.code,{children:"{distdir}"})," is replaced with the Pants ",(0,o.jsx)(t.code,{children:"distdir"}),"."]}),"\n",(0,o.jsxs)(t.li,{children:[(0,o.jsx)(t.code,{children:"{target_spec}"})," is replaced with the address of the applicable ",(0,o.jsx)(t.code,{children:"go_package"})," target with ",(0,o.jsx)(t.code,{children:"/"}),"\ncharacters replaced with dots (",(0,o.jsx)(t.code,{children:"."}),")."]}),"\n",(0,o.jsxs)(t.li,{children:[(0,o.jsx)(t.code,{children:"{import_path}"})," is replaced with the applicable package's import path. Subdirectories will be made\nfor any path components separated by ",(0,o.jsx)(t.code,{children:"/"})," characters."]}),"\n",(0,o.jsxs)(t.li,{children:[(0,o.jsx)(t.code,{children:"{import_path_escaped}"})," is replaced with the applicable package's import path but with\nslashes converted to underscores. This is deprecated and only exists to support behavior from\nearlier versions."]}),"\n"]})]}),(0,o.jsx)(t.h3,{id:"output_test_binary",children:(0,o.jsx)(t.code,{children:"output_test_binary"})}),(0,o.jsxs)(n.A,{cli_repr:"--[no-]go-test-output-test-binary",env_repr:"PANTS_GO_TEST_OUTPUT_TEST_BINARY",toml_repr:"[go-test]\noutput_test_binary = <bool>",default_repr:"False",children:[(0,o.jsx)(t.p,{children:"Write the test binary to the test extra output directory."}),(0,o.jsxs)(t.p,{children:["This is similar to the ",(0,o.jsx)(t.code,{children:"go test -c"})," option, but will still run the underlying test."]})]}),(0,o.jsx)(t.h2,{id:"deprecated-options",children:"Deprecated options"}),(0,o.jsx)(t.p,{children:"None"}),(0,o.jsx)(t.h2,{id:"related-subsystems",children:"Related subsystems"}),(0,o.jsx)(t.p,{children:"None"})]})]})}function _(e={}){const{wrapper:t}={...(0,s.R)(),...e.components};return t?(0,o.jsx)(t,{...e,children:(0,o.jsx)(p,{...e})}):p(e)}},87598:(e,t,r)=>{r.d(t,{A:()=>o});const o={options:"options_nrbo"}},142519:(e,t,r)=>{r.d(t,{A:()=>i});var o=r(474848),s=r(276634),n=r(528618);function i({children:e,cli_repr:t,env_repr:r,toml_repr:i,one_of:c,default_repr:l,target_field_name:d,removal_version:a,removal_hint:h}){return(0,o.jsxs)("div",{className:"margin-bottom--lg",children:[(0,o.jsx)("code",{style:{color:"var(--pants-reference-option-repr)"},children:t}),(0,o.jsx)("br",{}),(0,o.jsx)("code",{style:{color:"var(--pants-reference-option-repr)"},children:r}),(0,o.jsx)("br",{}),(0,o.jsx)(s.A,{language:"toml",title:"pants.toml",children:i}),(0,o.jsxs)("div",{style:{paddingLeft:"2em"},children:[(0,o.jsxs)("span",{children:[c&&(0,o.jsxs)("span",{children:["one of:"," ",(0,o.jsx)("code",{style:{color:"var(--ifm-color-success)"},children:c}),(0,o.jsx)("br",{})]}),"default:"," ",(0,o.jsx)("span",{style:{color:"var(--ifm-color-success)"},children:(l||"").includes("\n")?(0,o.jsx)("pre",{className:"padding--sm",children:l}):(0,o.jsx)("code",{children:l})})]}),(0,o.jsx)("br",{}),a&&(0,o.jsxs)("span",{style:{color:"var(--ifm-color-danger-darkest)"},children:["Deprecated, will be removed in version: ",a,".",(0,o.jsx)("br",{}),h,(0,o.jsx)("br",{})]}),e,d&&(0,o.jsxs)("span",{children:["Can be overriden by field",(0,o.jsx)("code",{children:d})," on"," ",(0,o.jsx)(n.A,{to:"../targets/local_environment",children:(0,o.jsx)("code",{children:"local_environment"})}),","," ",(0,o.jsx)(n.A,{to:"../targets/docker_environment",children:(0,o.jsx)("code",{children:"docker_environment"})}),", or"," ",(0,o.jsx)(n.A,{to:"../targets/remote_environment",children:(0,o.jsx)("code",{children:"remote_environment"})}),"targets."]})]})]})}}}]);