2023-01-13 12:27:21 +01:00
package coderdtest_test
import (
2026-08-26 16:17:06 +02:00
"encoding/json"
2026-11-10 17:42:30 -05:00
"fmt"
2023-01-13 12:27:21 +01:00
"go/ast"
"go/parser"
"go/token"
2026-11-10 17:42:30 -05:00
"slices"
2023-01-13 12:27:21 +01:00
"strings"
2026-11-09 07:37:35 +01:00
"sync"
2023-01-13 12:27:21 +01:00
"testing"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
2026-08-26 16:17:06 +02:00
"github.com/coder/coder/v2/coderd/apidoc"
2023-08-18 13:55:43 -05:00
"github.com/coder/coder/v2/coderd/coderdtest"
2023-01-13 12:27:21 +01:00
)
2026-11-09 07:37:35 +01:00
// swaggerDoc renders the spec once. swag's ReadDoc writes shared state, so
// parallel tests that each call it race.
var swaggerDoc = sync . OnceValue ( apidoc . SwaggerInfo . ReadDoc )
2023-01-13 12:27:21 +01:00
func TestEndpointsDocumented ( t * testing . T ) {
t . Parallel ()
2026-05-20 13:09:11 -04:00
swaggerComments , err := coderdtest . ParseSwaggerComments ( ".." , "../workspaceconnwatcher" )
2023-01-13 12:27:21 +01:00
require . NoError ( t , err , "can't parse swagger comments" )
2023-01-13 16:47:38 +01:00
require . NotEmpty ( t , swaggerComments , "swagger comments must be present" )
2023-01-13 12:27:21 +01:00
2026-09-11 03:48:56 +02:00
_ , _ , api := coderdtest . NewWithAPI ( t , nil )
2026-05-05 02:54:03 +05:00
coderdtest . VerifySwaggerDefinitions ( t , api . APIHandler , swaggerComments , coderdtest . WithSwaggerRoutePrefix ( "/api/v2" ))
2023-01-13 12:27:21 +01:00
}
2026-08-26 16:17:06 +02:00
func TestChatModelPathParametersFormatted ( t * testing . T ) {
t . Parallel ()
var swagger struct {
Paths map [ string ] map [ string ] struct {
Parameters [] struct {
Name string `json:"name"`
In string `json:"in"`
Format string `json:"format"`
} `json:"parameters"`
} `json:"paths"`
}
2026-11-09 07:37:35 +01:00
require . NoError ( t , json . Unmarshal ([] byte ( swaggerDoc ()), & swagger ))
2026-08-26 16:17:06 +02:00
operations := swagger . Paths [ "/api/v2/organizations/{organization}/chats/models/{model}" ]
for _ , method := range [] string { "get" , "patch" , "delete" } {
t . Run ( method , func ( t * testing . T ) {
t . Parallel ()
for _ , parameter := range operations [ method ]. Parameters {
if parameter . Name == "model" && parameter . In == "path" {
require . Equal ( t , "uuid" , parameter . Format )
return
}
}
require . Fail ( t , "model path parameter not found" )
})
}
}
2026-11-05 14:22:30 -05:00
// TestSwaggerParametersValid guards against parameter annotations that
// produce a wrong spec. Swagger 2.0 does not allow "example" on non-body
// parameters, swag writes format(...) on an array parameter to the array
// rather than its items, and a path parameter must appear in its route.
func TestSwaggerParametersValid ( t * testing . T ) {
t . Parallel ()
var swagger struct {
Paths map [ string ] map [ string ] struct {
Parameters [] struct {
Name string `json:"name"`
In string `json:"in"`
Type string `json:"type"`
Format string `json:"format"`
Example any `json:"example"`
} `json:"parameters"`
} `json:"paths"`
}
2026-11-09 07:37:35 +01:00
require . NoError ( t , json . Unmarshal ([] byte ( swaggerDoc ()), & swagger ))
2026-11-05 14:22:30 -05:00
require . NotEmpty ( t , swagger . Paths )
for path , operations := range swagger . Paths {
for method , operation := range operations {
for _ , parameter := range operation . Parameters {
if parameter . In != "body" {
assert . Nil ( t , parameter . Example , "%s %s: %s parameter %q must not have an example; use extensions(x-example=...)" , method , path , parameter . In , parameter . Name )
}
if parameter . Type == "array" {
assert . Empty ( t , parameter . Format , "%s %s: array parameter %q must not have a format; swag cannot set an item format, so state it in the description" , method , path , parameter . Name )
}
if parameter . In == "path" {
assert . Contains ( t , path , "{" + parameter . Name + "}" , "%s %s: path parameter %q is not in the route" , method , path , parameter . Name )
}
}
}
}
}
2023-01-13 12:27:21 +01:00
func TestSDKFieldsFormatted ( t * testing . T ) {
t . Parallel ()
fileSet := token . NewFileSet ()
nodes , err := parser . ParseDir ( fileSet , "../../codersdk" , nil , parser . ParseComments )
require . NoError ( t , err , "parser.ParseDir failed" )
for _ , node := range nodes {
ast . Inspect ( node , func ( n ast . Node ) bool {
typeSpec , ok := n .( * ast . TypeSpec )
if ! ok {
return true
}
structureName := typeSpec . Name
structType , ok := typeSpec . Type .( * ast . StructType )
if ! ok {
return true // not a structure
}
for _ , field := range structType . Fields . List {
selectorExpr , ok := field . Type .( * ast . SelectorExpr )
if ! ok {
continue // rather a basic, or primitive
}
if field . Tag == nil || ! strings . Contains ( field . Tag . Value , `json:"` ) {
continue // not a JSON property
}
switch selectorExpr . Sel . Name {
case "UUID" :
assert . Contains ( t , field . Tag . Value , `format:"uuid"` , `Swagger formatting requires to annotate the field with - format:"uuid". Location: %s/%s` , structureName , field . Names )
case "Time" :
assert . Contains ( t , field . Tag . Value , `format:"date-time"` , `Swagger formatting requires to annotate the field with - format:"date-time". Location: %s/%s` , structureName , field . Names )
}
}
return true
})
}
}
2026-11-10 17:42:30 -05:00
// TestSwaggerEnumsNotNarrowed checks every enum list in the spec. A property
// whose enum comes from an enums or oneof tag may list only values of its
// referenced type, and must list all of them unless the property is in
// allowedSubsets. No enum list may repeat a value, which Swagger 2.0 forbids.
func TestSwaggerEnumsNotNarrowed ( t * testing . T ) {
t . Parallel ()
// Fields that omit a value of their type on purpose. The ACL role fields
// omit the "" deleted sentinel, which only update requests send.
// CreateWorkspaceBuildOnSuccessRequest.transition and
// UpdateUserAppearanceSettingsRequest.theme_mode are request fields whose
// validate oneof tag accepts only some values. APIKey.scope is deprecated
// and lists only the legacy scopes. Keep this list as small as possible.
allowedSubsets := map [ string ] bool {
"codersdk.APIKey.scope" : true ,
"codersdk.ChatGroup.role" : true ,
"codersdk.ChatProjectGroup.role" : true ,
"codersdk.ChatProjectUser.role" : true ,
"codersdk.ChatUser.role" : true ,
"codersdk.CreateWorkspaceBuildOnSuccessRequest.transition" : true ,
"codersdk.MCPServerConfigGroup.role" : true ,
"codersdk.MCPServerConfigUser.role" : true ,
"codersdk.OrganizationSkillGroup.role" : true ,
"codersdk.OrganizationSkillUser.role" : true ,
"codersdk.TemplateGroup.role" : true ,
"codersdk.TemplateUser.role" : true ,
"codersdk.UpdateUserAppearanceSettingsRequest.theme_mode" : true ,
"codersdk.WorkspaceGroup.role" : true ,
"codersdk.WorkspaceUser.role" : true ,
}
type schema struct {
Ref string `json:"$ref"`
AllOf [] struct {
Ref string `json:"$ref"`
} `json:"allOf"`
Enum [] any `json:"enum"`
Items * struct {
Ref string `json:"$ref"`
Enum [] any `json:"enum"`
} `json:"items"`
}
var swagger struct {
Definitions map [ string ] struct {
Enum [] any `json:"enum"`
Properties map [ string ] schema `json:"properties"`
} `json:"definitions"`
Paths map [ string ] map [ string ] struct {
Parameters [] struct {
Name string `json:"name"`
Enum [] any `json:"enum"`
Items * struct {
Enum [] any `json:"enum"`
} `json:"items"`
} `json:"parameters"`
} `json:"paths"`
}
2026-11-11 23:50:14 +01:00
require . NoError ( t , json . Unmarshal ([] byte ( swaggerDoc ()), & swagger ))
2026-11-10 17:42:30 -05:00
assertNoDuplicates := func ( where string , values [] any ) {
t . Helper ()
seen := map [ string ] bool {}
for _ , v := range enumStrings ( values ) {
assert . Falsef ( t , seen [ v ], "%s lists enum value %q more than once" , where , v )
seen [ v ] = true
}
}
seenSubsets := map [ string ] bool {}
assertEnumMatchesType := func ( key , ref string , inline [] any ) {
t . Helper ()
if ref == "" || len ( inline ) == 0 {
return
}
named := swagger . Definitions [ strings . TrimPrefix ( ref , "#/definitions/" )]. Enum
have := enumStrings ( inline )
want := enumStrings ( named )
for _ , v := range have {
assert . Truef ( t , slices . Contains ( want , v ), "%s lists %q, which type %s does not have; add the constant to the type if the API returns or accepts it, otherwise remove the value from the field's enums tag" , key , v , ref )
}
if slices . Equal ( have , want ) {
return
}
seenSubsets [ key ] = true
assert . Truef ( t , allowedSubsets [ key ], "%s lists %v but its type %s lists %v; remove the narrowing enums tag so the spec lists every value, or add the field to allowedSubsets if the subset is intentional, as for a validate oneof tag" , key , inline , ref , named )
}
for defName , def := range swagger . Definitions {
assertNoDuplicates ( defName , def . Enum )
for propName , prop := range def . Properties {
key := defName + "." + propName
assertNoDuplicates ( key , prop . Enum )
ref := prop . Ref
if ref == "" && len ( prop . AllOf ) > 0 {
ref = prop . AllOf [ 0 ]. Ref
}
assertEnumMatchesType ( key , ref , prop . Enum )
if prop . Items != nil {
assertNoDuplicates ( key , prop . Items . Enum )
assertEnumMatchesType ( key , prop . Items . Ref , prop . Items . Enum )
}
}
}
for key := range allowedSubsets {
assert . Truef ( t , seenSubsets [ key ], "%s is in allowedSubsets but is no longer a subset of its type; remove it" , key )
}
for route , methods := range swagger . Paths {
for method , op := range methods {
for _ , param := range op . Parameters {
where := method + " " + route + " parameter " + param . Name
assertNoDuplicates ( where , param . Enum )
if param . Items != nil {
assertNoDuplicates ( where , param . Items . Enum )
}
}
}
}
}
// enumStrings returns the sorted string form of enum values, which may be numbers.
func enumStrings ( values [] any ) [] string {
out := make ([] string , 0 , len ( values ))
for _ , v := range values {
out = append ( out , fmt . Sprint ( v ))
}
slices . Sort ( out )
return out
}