coder · ethanndickson · May 22, 2026 · May 22, 2026 · ethanndickson · May 22, 2026
diff --git a/.claude/docs/TESTING.md b/.claude/docs/TESTING.md
@@ -30,7 +30,16 @@ issues.
 
 ### Test Package Naming
 
-- **Test packages**: Use `package_test` naming (e.g., `identityprovider_test`) for black-box testing
+- **Black-box tests**: Default to a `package foo_test` test file (e.g.,
+  `identityprovider_test`). This is what the `testpackage` linter enforces.
+- **White-box / internal tests**: When a test needs to touch unexported
+  symbols, put it in a file named `*_internal_test.go` with `package foo`.
+  The `testpackage` linter's `skip-regexp` already exempts that filename
+  suffix, so no `//nolint:testpackage` directive is needed.
+- **Do not add `//nolint:testpackage`.** If a test needs internal access,
+  rename the file to `*_internal_test.go` instead. A directive plus a
+  justification comment is strictly worse than the established naming
+  convention, and the repo standardizes on the latter.
 
 ## RFC Protocol Testing
 
@@ -50,7 +59,7 @@ issues.
 
 ### Test File Structure
 
-```
+```text
 coderd/
 ├── oauth2.go                    # Implementation
 ├── oauth2_test.go              # Main tests
@@ -69,20 +78,20 @@ coderd/
 
 ### Running Tests
 
-| Command | Purpose |
-|---------|---------|
-| `make test` | Run all Go tests |
-| `make test RUN=TestFunctionName` | Run specific test |
-| `go test -v ./path/to/package -run TestFunctionName` | Run test with verbose output |
-| `make test-race` | Run tests with Go race detector |
-| `make test-e2e` | Run end-to-end tests |
+| Command                                              | Purpose                         |
+|------------------------------------------------------|---------------------------------|
+| `make test`                                          | Run all Go tests                |
+| `make test RUN=TestFunctionName`                     | Run specific test               |
+| `go test -v ./path/to/package -run TestFunctionName` | Run test with verbose output    |
+| `make test-race`                                     | Run tests with Go race detector |
+| `make test-e2e`                                      | Run end-to-end tests            |
 
 ### Frontend Testing
 
-| Command | Purpose |
-|---------|---------|
-| `pnpm test` | Run frontend tests |
-| `pnpm check` | Run code checks |
+| Command      | Purpose            |
+|--------------|--------------------|
+| `pnpm test`  | Run frontend tests |
+| `pnpm check` | Run code checks    |
 
 ## Common Testing Issues
 
@@ -218,6 +227,7 @@ func BenchmarkFunction(b *testing.B) {
 ```
 
 Run benchmarks with:
+
 ```bash
 go test -bench=. -benchmem ./package/path
 ```
diff --git a/...t/reconnectingpty/reconnectingpty_test.go → ...ctingpty/reconnectingpty_internal_test.go b/...t/reconnectingpty/reconnectingpty_test.go → ...ctingpty/reconnectingpty_internal_test.go
@@ -1,4 +1,3 @@
-//nolint:testpackage // Tests private env helpers directly.
 package reconnectingpty
 
 import (

diff --git a/agent/write_secret_files_test.go → agent/write_secret_files_internal_test.go b/agent/write_secret_files_test.go → agent/write_secret_files_internal_test.go
@@ -1,4 +1,4 @@
-package agent //nolint:testpackage // Exercises internal agent secrets handling.
+package agent
 
 import (
 	"testing"

diff --git a/aibridge/intercept/apidump/apidump_test.go → ...ntercept/apidump/apidump_internal_test.go b/aibridge/intercept/apidump/apidump_test.go → ...ntercept/apidump/apidump_internal_test.go
@@ -1,4 +1,4 @@
-package apidump //nolint:testpackage // tests unexported internals
+package apidump
 
 import (
 	"bytes"

diff --git a/aibridge/intercept/apidump/headers_test.go → ...ntercept/apidump/headers_internal_test.go b/aibridge/intercept/apidump/headers_test.go → ...ntercept/apidump/headers_internal_test.go
@@ -1,4 +1,4 @@
-package apidump //nolint:testpackage // tests unexported internals
+package apidump
 
 import (
 	"bytes"

diff --git a/aibridge/intercept/apidump/streaming_test.go → ...ercept/apidump/streaming_internal_test.go b/aibridge/intercept/apidump/streaming_test.go → ...ercept/apidump/streaming_internal_test.go
@@ -1,4 +1,4 @@
-package apidump //nolint:testpackage // shares test helpers with apidump_test.go
+package apidump
 
 import (
 	"bytes"

diff --git a/...ge/intercept/chatcompletions/base_test.go → ...ept/chatcompletions/base_internal_test.go b/...ge/intercept/chatcompletions/base_test.go → ...ept/chatcompletions/base_internal_test.go
@@ -1,4 +1,4 @@
-package chatcompletions //nolint:testpackage // tests unexported internals
+package chatcompletions
 
 import (
 	"context"

diff --git a/...ntercept/chatcompletions/blocking_test.go → ...chatcompletions/blocking_internal_test.go b/...ntercept/chatcompletions/blocking_test.go → ...chatcompletions/blocking_internal_test.go
@@ -1,4 +1,4 @@
-package chatcompletions //nolint:testpackage // tests unexported internals
+package chatcompletions
 
 import (
 	"context"

diff --git a/...ercept/chatcompletions/paramswrap_test.go → ...atcompletions/paramswrap_internal_test.go b/...ercept/chatcompletions/paramswrap_test.go → ...atcompletions/paramswrap_internal_test.go
@@ -1,4 +1,4 @@
-package chatcompletions //nolint:testpackage // tests unexported internals
+package chatcompletions
 
 import (
 	"fmt"

diff --git a/...tercept/chatcompletions/streaming_test.go → ...hatcompletions/streaming_internal_test.go b/...tercept/chatcompletions/streaming_test.go → ...hatcompletions/streaming_internal_test.go
@@ -1,4 +1,4 @@
-package chatcompletions //nolint:testpackage // tests unexported internals
+package chatcompletions
 
 import (
 	"io"

diff --git a/aibridge/intercept/messages/base_test.go → .../intercept/messages/base_internal_test.go b/aibridge/intercept/messages/base_test.go → .../intercept/messages/base_internal_test.go
@@ -1,4 +1,4 @@
-package messages //nolint:testpackage // tests unexported internals
+package messages
 
 import (
 	"context"

diff --git a/aibridge/intercept/messages/blocking_test.go → ...ercept/messages/blocking_internal_test.go b/aibridge/intercept/messages/blocking_test.go → ...ercept/messages/blocking_internal_test.go
@@ -1,4 +1,4 @@
-package messages //nolint:testpackage // tests unexported internals
+package messages
 
 import (
 	"io"

diff --git a/...dge/intercept/messages/reqpayload_test.go → ...cept/messages/reqpayload_internal_test.go b/...dge/intercept/messages/reqpayload_test.go → ...cept/messages/reqpayload_internal_test.go
@@ -1,4 +1,4 @@
-package messages //nolint:testpackage // tests unexported internals
+package messages
 
 import (
 	"testing"

diff --git a/...idge/intercept/messages/streaming_test.go → ...rcept/messages/streaming_internal_test.go b/...idge/intercept/messages/streaming_test.go → ...rcept/messages/streaming_internal_test.go
@@ -1,4 +1,4 @@
-package messages //nolint:testpackage // tests unexported internals
+package messages
 
 import (
 	"context"

diff --git a/aibridge/intercept/responses/base_test.go → ...intercept/responses/base_internal_test.go b/aibridge/intercept/responses/base_test.go → ...intercept/responses/base_internal_test.go
@@ -1,4 +1,4 @@
-package responses //nolint:testpackage // tests unexported internals
+package responses
 
 import (
 	"context"

diff --git a/...idge/intercept/responses/blocking_test.go → ...rcept/responses/blocking_internal_test.go b/...idge/intercept/responses/blocking_test.go → ...rcept/responses/blocking_internal_test.go
@@ -1,4 +1,4 @@
-package responses //nolint:testpackage // tests unexported internals
+package responses
 
 import (
 	"context"

diff --git a/...ge/intercept/responses/reqpayload_test.go → ...ept/responses/reqpayload_internal_test.go b/...ge/intercept/responses/reqpayload_test.go → ...ept/responses/reqpayload_internal_test.go
@@ -1,4 +1,4 @@
-package responses //nolint:testpackage // tests unexported internals
+package responses
 
 import (
 	"encoding/json"

diff --git a/...dge/intercept/responses/streaming_test.go → ...cept/responses/streaming_internal_test.go b/...dge/intercept/responses/streaming_test.go → ...cept/responses/streaming_internal_test.go
@@ -1,4 +1,4 @@
-package responses //nolint:testpackage // tests unexported internals
+package responses
 
 import (
 	"io"

diff --git a/.../internal/integrationtest/apidump_test.go → .../integrationtest/apidump_internal_test.go b/.../internal/integrationtest/apidump_test.go → .../integrationtest/apidump_internal_test.go
@@ -1,4 +1,4 @@
-package integrationtest //nolint:testpackage // tests unexported internals
+package integrationtest
 
 import (
 	"bufio"

diff --git a/...e/internal/integrationtest/bridge_test.go → ...l/integrationtest/bridge_internal_test.go b/...e/internal/integrationtest/bridge_test.go → ...l/integrationtest/bridge_internal_test.go
@@ -1,4 +1,4 @@
-package integrationtest //nolint:testpackage // tests unexported internals
+package integrationtest
 
 import (
 	"bytes"

diff --git a/...l/integrationtest/circuit_breaker_test.go → ...tiontest/circuit_breaker_internal_test.go b/...l/integrationtest/circuit_breaker_test.go → ...tiontest/circuit_breaker_internal_test.go
@@ -1,4 +1,4 @@
-package integrationtest //nolint:testpackage // tests unexported internals
+package integrationtest
 
 import (
 	"fmt"

diff --git a/.../integrationtest/keypool_failover_test.go → ...iontest/keypool_failover_internal_test.go b/.../integrationtest/keypool_failover_test.go → ...iontest/keypool_failover_internal_test.go
@@ -1,4 +1,4 @@
-package integrationtest //nolint:testpackage // tests unexported internals
+package integrationtest
 
 import (
 	"fmt"

diff --git a/.../internal/integrationtest/metrics_test.go → .../integrationtest/metrics_internal_test.go b/.../internal/integrationtest/metrics_test.go → .../integrationtest/metrics_internal_test.go
@@ -1,4 +1,4 @@
-package integrationtest //nolint:testpackage // tests unexported internals
+package integrationtest
 
 import (
 	"bytes"

diff --git a/...nternal/integrationtest/responses_test.go → ...ntegrationtest/responses_internal_test.go b/...nternal/integrationtest/responses_test.go → ...ntegrationtest/responses_internal_test.go
@@ -1,4 +1,4 @@
-package integrationtest //nolint:testpackage // tests unexported internals
+package integrationtest
 
 import (
 	"context"

diff --git a/...ge/internal/integrationtest/trace_test.go → ...al/integrationtest/trace_internal_test.go b/...ge/internal/integrationtest/trace_test.go → ...al/integrationtest/trace_internal_test.go
@@ -1,4 +1,4 @@
-package integrationtest //nolint:testpackage // tests unexported internals
+package integrationtest
 
 import (
 	"context"

diff --git a/aibridge/passthrough_test.go → aibridge/passthrough_internal_test.go b/aibridge/passthrough_test.go → aibridge/passthrough_internal_test.go
@@ -1,4 +1,4 @@
-package aibridge //nolint:testpackage // tests unexported newPassthroughRouter
+package aibridge
 
 import (
 	"crypto/tls"

diff --git a/aibridge/provider/anthropic_test.go → aibridge/provider/anthropic_internal_test.go b/aibridge/provider/anthropic_test.go → aibridge/provider/anthropic_internal_test.go
@@ -1,4 +1,4 @@
-package provider //nolint:testpackage // tests unexported internals
+package provider
 
 import (
 	"bytes"

diff --git a/aibridge/provider/copilot_test.go → aibridge/provider/copilot_internal_test.go b/aibridge/provider/copilot_test.go → aibridge/provider/copilot_internal_test.go
@@ -1,4 +1,4 @@
-package provider //nolint:testpackage // tests unexported internals
+package provider
 
 import (
 	"bytes"

diff --git a/aibridge/provider/openai_test.go → aibridge/provider/openai_internal_test.go b/aibridge/provider/openai_test.go → aibridge/provider/openai_internal_test.go
@@ -1,4 +1,4 @@
-package provider //nolint:testpackage // tests unexported internals
+package provider
 
 import (
 	"bytes"

diff --git a/coderd/oauth2provider/authorize_internal_test.go b/coderd/oauth2provider/authorize_internal_test.go
@@ -1,4 +1,3 @@
-//nolint:testpackage // Internal test for unexported hashOAuth2State helper.
 package oauth2provider
 
 import (

diff --git a/coderd/templates_meta_update_internal_test.go b/coderd/templates_meta_update_internal_test.go
@@ -1,4 +1,4 @@
-package coderd //nolint:testpackage // Tests the unexported resolveTemplateMetaUpdate helper.
+package coderd
 
 import (
 	"reflect"

diff --git a/coderd/x/chatd/advisor_internal_test.go b/coderd/x/chatd/advisor_internal_test.go
@@ -1,4 +1,4 @@
-package chatd //nolint:testpackage // Accesses unexported advisor helpers.
+package chatd
 
 import (
 	"context"

diff --git a/coderd/x/chatd/attachments_test.go → coderd/x/chatd/attachments_internal_test.go b/coderd/x/chatd/attachments_test.go → coderd/x/chatd/attachments_internal_test.go
@@ -1,4 +1,4 @@
-package chatd //nolint:testpackage
+package chatd
 
 import (
 	"context"

diff --git a/.../x/chatd/chatdebug/model_coverage_test.go → ...chatdebug/model_coverage_internal_test.go b/.../x/chatd/chatdebug/model_coverage_test.go → ...chatdebug/model_coverage_internal_test.go
@@ -1,4 +1,4 @@
-package chatdebug //nolint:testpackage // Checks unexported normalized structs against fantasy source types.
+package chatdebug
 
 import (
 	"reflect"

diff --git a/...atd/chatdebug/model_normalization_test.go → ...ebug/model_normalization_internal_test.go b/...atd/chatdebug/model_normalization_test.go → ...ebug/model_normalization_internal_test.go
@@ -1,4 +1,4 @@
-package chatdebug //nolint:testpackage // Uses unexported normalization helpers.
+package chatdebug
 
 import (
 	"context"

diff --git a/coderd/x/chatd/chatdebug/recorder_test.go → ...chatd/chatdebug/recorder_internal_test.go b/coderd/x/chatd/chatdebug/recorder_test.go → ...chatd/chatdebug/recorder_internal_test.go
@@ -1,4 +1,4 @@
-package chatdebug //nolint:testpackage // Uses unexported recorder helpers.
+package chatdebug
 
 import (
 	"context"

diff --git a/coderd/x/chatd/chatdebug/reuse_step_test.go → ...atd/chatdebug/reuse_step_internal_test.go b/coderd/x/chatd/chatdebug/reuse_step_test.go → ...atd/chatdebug/reuse_step_internal_test.go
@@ -1,4 +1,4 @@
-package chatdebug //nolint:testpackage // Uses unexported recorder helpers.
+package chatdebug
 
 import (
 	"context"

diff --git a/coderd/x/chatd/chatdebug/transport_test.go → ...hatd/chatdebug/transport_internal_test.go b/coderd/x/chatd/chatdebug/transport_test.go → ...hatd/chatdebug/transport_internal_test.go
@@ -1,4 +1,4 @@
-package chatdebug //nolint:testpackage // Uses unexported recorder helpers.
+package chatdebug
 
 import (
 	"bytes"

diff --git a/coderd/x/chatd/chatloop/chatloop_test.go → ...td/chatloop/chatloop_run_internal_test.go b/coderd/x/chatd/chatloop/chatloop_test.go → ...td/chatloop/chatloop_run_internal_test.go
@@ -1,4 +1,4 @@
-package chatloop //nolint:testpackage // Uses internal symbols.
+package chatloop
 
 import (
 	"context"

diff --git a/coderd/x/chatd/chatloop/compaction_test.go → ...hatd/chatloop/compaction_internal_test.go b/coderd/x/chatd/chatloop/compaction_test.go → ...hatd/chatloop/compaction_internal_test.go
@@ -1,4 +1,4 @@
-package chatloop //nolint:testpackage // Uses internal symbols.
+package chatloop
 
 import (
 	"context"

diff --git a/.../x/chatd/chattool/askuserquestion_test.go → ...chattool/askuserquestion_internal_test.go b/.../x/chatd/chattool/askuserquestion_test.go → ...chattool/askuserquestion_internal_test.go
@@ -1,4 +1,4 @@
-package chattool //nolint:testpackage // Uses internal symbols.
+package chattool
 
 import (
 	"testing"

diff --git a/.../x/chatd/chattool/createworkspace_test.go → ...chattool/createworkspace_internal_test.go b/.../x/chatd/chattool/createworkspace_test.go → ...chattool/createworkspace_internal_test.go
@@ -1,4 +1,4 @@
-package chattool //nolint:testpackage // Uses internal symbols.
+package chattool
 
 import (
 	"context"

diff --git a/coderd/x/chatd/configcache_test.go → coderd/x/chatd/configcache_internal_test.go b/coderd/x/chatd/configcache_test.go → coderd/x/chatd/configcache_internal_test.go
@@ -1,4 +1,4 @@
-package chatd //nolint:testpackage // Uses internal cache state.
+package chatd
 
 import (
 	"context"

diff --git a/coderd/x/chatd/dialvalidation_test.go → ...d/x/chatd/dialvalidation_internal_test.go b/coderd/x/chatd/dialvalidation_test.go → ...d/x/chatd/dialvalidation_internal_test.go
@@ -1,4 +1,4 @@
-package chatd //nolint:testpackage // Uses internal symbols.
+package chatd
 
 import (
 	"context"

diff --git a/coderd/x/chatd/instruction_test.go → coderd/x/chatd/instruction_internal_test.go b/coderd/x/chatd/instruction_test.go → coderd/x/chatd/instruction_internal_test.go
@@ -1,4 +1,4 @@
-package chatd //nolint:testpackage // Uses internal symbols.
+package chatd
 
 import (
 	"encoding/json"

diff --git a/coderd/x/chatd/quickgen_test.go → coderd/x/chatd/quickgen_internal_test.go b/coderd/x/chatd/quickgen_test.go → coderd/x/chatd/quickgen_internal_test.go
@@ -1,4 +1,4 @@
-package chatd //nolint:testpackage // Keeps internal helper tests in-package.
+package chatd
 
 import (
 	"context"

diff --git a/coderd/x/chatd/store_chat_attachment_test.go → ...td/store_chat_attachment_internal_test.go b/coderd/x/chatd/store_chat_attachment_test.go → ...td/store_chat_attachment_internal_test.go
@@ -1,4 +1,4 @@
-package chatd //nolint:testpackage
+package chatd
 
 import (
 	"context"

diff --git a/coderd/x/chatd/title_override_test.go → ...d/x/chatd/title_override_internal_test.go b/coderd/x/chatd/title_override_test.go → ...d/x/chatd/title_override_internal_test.go
@@ -1,4 +1,4 @@
-package chatd //nolint:testpackage // Tests internal title override helpers.
+package chatd
 
 import (
 	"context"

diff --git a/coderd/x/chatd/usagelimit_test.go → coderd/x/chatd/usagelimit_internal_test.go b/coderd/x/chatd/usagelimit_test.go → coderd/x/chatd/usagelimit_internal_test.go
@@ -1,4 +1,4 @@
-package chatd //nolint:testpackage // Keeps chatd unit tests in the package.
+package chatd
 
 import (
 	"testing"

diff --git a/codersdk/pagination_test.go → codersdk/pagination_internal_test.go b/codersdk/pagination_test.go → codersdk/pagination_internal_test.go
@@ -1,4 +1,3 @@
-//nolint:testpackage
 package codersdk
 
 import (

diff --git a/codersdk/workspacesdk/agentconn_test.go → ...k/workspacesdk/agentconn_internal_test.go b/codersdk/workspacesdk/agentconn_test.go → ...k/workspacesdk/agentconn_internal_test.go
@@ -1,4 +1,3 @@
-//nolint:testpackage // This test exercises the internal query builder directly because agent requests need a live tailnet connection.
 package workspacesdk
 
 import (

diff --git a/provisionerd/runner/runner_test.go → provisionerd/runner/runner_internal_test.go b/provisionerd/runner/runner_test.go → provisionerd/runner/runner_internal_test.go
@@ -1,4 +1,4 @@
-package runner //nolint:testpackage // Tests unexported failure classification helpers.
+package runner
 
 import (
 	"testing"