Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.
Go agentagenticaichatbotdsh-pluginembeddingsevaluationgenerative-aigolangknowledge-basellmmulti-tenantollamaopenaiquestion-answeringragrerankingsemantic-searchvector-searchwiki
package docs_test
import (
"encoding/json"
"os"
"reflect"
"strings"
"testing"
docs "github.com/Tencent/WeKnora/docs"
"github.com/Tencent/WeKnora/internal/types"
"gopkg.in/yaml.v3"
)
type swaggerDocumentCase struct {
name string
loadSpec func(t *testing.T) []byte
parse func([]byte, any) error
}
type swaggerParameter struct {
Name string `json:"name" yaml:"name"`
In string `json:"in" yaml:"in"`
Type string `json:"type" yaml:"type"`
Required bool `json:"required" yaml:"required"`
}
type swaggerOperation struct {
Parameters []swaggerParameter `json:"parameters" yaml:"parameters"`
}
func swaggerDocuments() []swaggerDocumentCase {
return []swaggerDocumentCase{
{
name: "registered document",
loadSpec: func(t *testing.T) []byte {
t.Helper()
return []byte(docs.SwaggerInfo.ReadDoc())
},
parse: json.Unmarshal,
},
{
name: "swagger.json",
loadSpec: func(t *testing.T) []byte {
t.Helper()
return readSwaggerFile(t, "swagger.json")
},
parse: json.Unmarshal,
},
{
name: "swagger.yaml",
loadSpec: func(t *testing.T) []byte {
t.Helper()
return readSwaggerFile(t, "swagger.yaml")
},
parse: yaml.Unmarshal,
},
}
}
func TestKnowledgeSearchRouteContract(t *testing.T) {
for _, tt := range swaggerDocuments() {
t.Run(tt.name, func(t *testing.T) {
assertKnowledgeSearchRouteContract(t, tt.loadSpec(t), tt.parse)
})
}
}
func TestImagePipelineAgentKeysContract(t *testing.T) {
const want = "default.caption_enabled|default.ocr_enabled"
field, ok := reflect.TypeOf(types.ImageProcessingConfig{}).FieldByName("ImagePipelineParams")
if !ok {
t.Fatal("ImagePipelineParams field is missing")
}
if !strings.Contains(
","+field.Tag.Get("extensions")+",",
",x-agent-keys="+want+",",
) {
t.Fatalf("ImagePipelineParams must expose the active switch slots: %s", field.Tag)
}
for _, tt := range swaggerDocuments() {
t.Run(tt.name, func(t *testing.T) {
var spec struct {
Definitions map[string]struct {
Properties map[string]struct {
AgentKeys string `json:"x-agent-keys" yaml:"x-agent-keys"`
} `json:"properties" yaml:"properties"`
} `json:"definitions" yaml:"definitions"`
}
if err := tt.parse(tt.loadSpec(t), &spec); err != nil {
t.Fatal(err)
}
got := spec.Definitions["github_com_Tencent_WeKnora_internal_types.ImageProcessingConfig"].
Properties["image_pipeline_params"].AgentKeys
if got != want {
t.Errorf("image_pipeline_params agent keys = %q, want %q", got, want)
}
})
}
}
func TestAutomationAssistantContract(t *testing.T) {
for _, tt := range swaggerDocuments() {
t.Run(tt.name, func(t *testing.T) {
var spec struct {
Definitions map[string]struct {
Properties map[string]any `json:"properties" yaml:"properties"`
} `json:"definitions" yaml:"definitions"`
}
if err := tt.parse(tt.loadSpec(t), &spec); err != nil {
t.Fatal(err)
}
for _, name := range []string{
"internal_handler.CreateAutomationRequest",
"github_com_Tencent_WeKnora_internal_types.AutomationPatch",
"github_com_Tencent_WeKnora_internal_types.Automation",
} {
properties := spec.Definitions[name].Properties
if _, ok := properties["agent_id"]; ok {
t.Errorf("%s must not expose executor selection", name)
}
for _, field := range []string{"instruction", "model_id"} {
if _, ok := properties[field]; !ok {
t.Errorf("%s must expose %s", name, field)
}
}
}
})
}
}
func TestReleaseAPIContracts(t *testing.T) {
for _, tt := range swaggerDocuments() {
t.Run(tt.name, func(t *testing.T) {
var spec struct {
BasePath string `json:"basePath" yaml:"basePath"`
Paths map[string]map[string]any `json:"paths" yaml:"paths"`
Definitions map[string]struct {
Properties map[string]struct {
Type string `json:"type" yaml:"type"`
} `json:"properties" yaml:"properties"`
} `json:"definitions" yaml:"definitions"`
}
if err := tt.parse(tt.loadSpec(t), &spec); err != nil {
t.Fatal(err)
}
if spec.BasePath != "/api/v1" {
t.Fatalf("unexpected API base path %q", spec.BasePath)
}
for path := range spec.Paths {
if strings.HasPrefix(path, spec.BasePath+"/") {
t.Errorf("route %s repeats the API base path", path)
}
}
for path, methods := range map[string][]string{
"/knowledge/{id}/spans": {"get"},
"/knowledge-bases/{id}/images": {"get", "post"},
"/wiki-search": {"post"},
"/agents/tools": {"get"},
"/system/admin/users": {"get"},
"/system/admin/users/status": {"post"},
"/system/admin/model-catalog": {"get", "put"},
"/system/admin/model-catalog/preview": {"post"},
} {
for _, method := range methods {
if _, ok := spec.Paths[path][method]; !ok {
t.Errorf("missing %s %s", method, path)
}
}
}
for _, name := range []string{"CatalogUpdate", "CatalogState", "CatalogRevision"} {
definition := "github_com_Tencent_WeKnora_internal_application_service." + name
if spec.Definitions[definition].Properties["overlay"].Type != "object" {
t.Errorf("%s.overlay must be a JSON object", name)
}
}
})
}
}
func TestGraphSearchContract(t *testing.T) {
for _, tt := range swaggerDocuments() {
t.Run(tt.name, func(t *testing.T) {
var spec struct {
Paths map[string]map[string]any `json:"paths" yaml:"paths"`
Definitions map[string]struct {
Properties map[string]any `json:"properties" yaml:"properties"`
} `json:"definitions" yaml:"definitions"`
}
if err := tt.parse(tt.loadSpec(t), &spec); err != nil {
t.Fatal(err)
}
methods := spec.Paths["/knowledge-bases/{id}/graph-search"]
if methods["post"] == nil || len(methods) != 1 {
t.Fatal("graph-search must be documented as a POST-only endpoint")
}
const prefix = "github_com_Tencent_WeKnora_internal_types."
for definition, fields := range map[string][]string{
"GraphSearchResult": {"entities", "relationships", "source_chunks", "meta"},
"GraphSearchEntity": {"id", "knowledge_id", "source_chunk_ids"},
"GraphSearchRelation": {"source_id", "target_id", "source_chunk_ids"},
"GraphSearchSourceChunk": {"content_truncated", "title_truncated"},
"GraphSearchMeta": {"truncated", "truncation_reasons"},
} {
properties := spec.Definitions[prefix+definition].Properties
for _, field := range fields {
if properties[field] == nil {
t.Errorf("%s.%s must be documented", definition, field)
}
}
for _, hidden := range []string{"tenant_id", "knowledge_base_id", "element_id"} {
if definition != "GraphSearchResult" && properties[hidden] != nil {
t.Errorf("%s leaks internal field %s", definition, hidden)
}
}
}
})
}
}
func TestModelDeleteUsageContract(t *testing.T) {
for _, tt := range swaggerDocuments() {
t.Run(tt.name, func(t *testing.T) {
assertModelDeleteUsageContract(t, tt.loadSpec(t), tt.parse)
})
}
}
func TestFAQEnabledFilterContract(t *testing.T) {
for _, tt := range swaggerDocuments() {
t.Run(tt.name, func(t *testing.T) {
assertFAQEnabledFilterContract(t, tt.loadSpec(t), tt.parse)
})
}
}
func TestWikiPageBacklinkTitlesContract(t *testing.T) {
for _, tt := range swaggerDocuments() {
t.Run(tt.name, func(t *testing.T) {
var spec struct {
Paths map[string]map[string]struct {
Responses map[string]struct {
Schema struct {
Ref string `json:"$ref" yaml:"$ref"`
} `json:"schema" yaml:"schema"`
} `json:"responses" yaml:"responses"`
} `json:"paths" yaml:"paths"`
Definitions map[string]struct {
Properties map[string]map[string]any `json:"properties" yaml:"properties"`
} `json:"definitions" yaml:"definitions"`
}
if err := tt.parse(tt.loadSpec(t), &spec); err != nil {
t.Fatal(err)
}
const detail = "github_com_Tencent_WeKnora_internal_types.WikiPageDetail"
get := spec.Paths["/knowledgebase/{kb_id}/wiki/pages/{slug}"]["get"]
if get.Responses["200"].Schema.Ref != "#/definitions/"+detail {
t.Fatal("page detail response must expose backlink titles")
}
properties := spec.Definitions[detail].Properties
titles := properties["in_link_titles"]
values, ok := titles["additionalProperties"].(map[string]any)
if titles["type"] != "object" || !ok || values["type"] != "string" {
t.Fatal("in_link_titles must be a string-valued map")
}
for field := range spec.Definitions["github_com_Tencent_WeKnora_internal_types.WikiPage"].Properties {
if _, ok := properties[field]; !ok {
t.Errorf("page detail dropped existing field %s", field)
}
}
if _, ok := spec.Paths["/knowledgebase/{kb_id}/wiki/page-titles"]; ok {
t.Fatal("obsolete standalone title endpoint remains documented")
}
})
}
}
func readSwaggerFile(t *testing.T, name string) []byte {
t.Helper()
data, err := os.ReadFile(name)
if err != nil {
t.Fatalf("read %s: %v", name, err)
}
return data
}
func assertKnowledgeSearchRouteContract(t *testing.T, data []byte, parse func([]byte, any) error) {
t.Helper()
var spec struct {
Paths map[string]map[string]any `json:"paths" yaml:"paths"`
}
if err := parse(data, &spec); err != nil {
t.Fatalf("parse generated Swagger document: %v", err)
}
knowledgeSearch, ok := spec.Paths["/knowledge-search"]
if !ok {
t.Fatal("generated Swagger document does not expose /knowledge-search")
}
if _, ok := knowledgeSearch["post"]; !ok {
t.Fatal("generated Swagger document does not expose POST /knowledge-search")
}
if staleRoute, ok := spec.Paths["/sessions/search"]; ok {
if _, ok := staleRoute["post"]; ok {
t.Fatal("generated Swagger document still exposes stale POST /sessions/search")
}
}
}
func assertModelDeleteUsageContract(t *testing.T, data []byte, parse func([]byte, any) error) {
t.Helper()
var spec struct {
Paths map[string]map[string]struct {
Responses map[string]any `json:"responses" yaml:"responses"`
} `json:"paths" yaml:"paths"`
Definitions map[string]map[string]any `json:"definitions" yaml:"definitions"`
}
if err := parse(data, &spec); err != nil {
t.Fatalf("parse generated Swagger document: %v", err)
}
models, ok := spec.Paths["/models/{id}"]
if !ok {
t.Fatal("generated Swagger document does not expose /models/{id}")
}
deleteOperation, ok := models["delete"]
if !ok {
t.Fatal("generated Swagger document does not expose DELETE /models/{id}")
}
if _, ok := deleteOperation.Responses["400"]; !ok {
t.Fatal("model DELETE Swagger contract does not document the model-in-use 400 response")
}
const errorCodeDefinition = "github_com_Tencent_WeKnora_internal_errors.ErrorCode"
errorCodes, ok := spec.Definitions[errorCodeDefinition]
if !ok {
t.Fatalf("generated Swagger document does not expose %s", errorCodeDefinition)
}
enum, ok := errorCodes["enum"].([]any)
if !ok {
t.Fatalf("generated Swagger ErrorCode enum has unexpected shape: %#v", errorCodes["enum"])
}
enumVarNames, ok := errorCodes["x-enum-varnames"].([]any)
if !ok {
t.Fatalf("generated Swagger ErrorCode names have unexpected shape: %#v", errorCodes["x-enum-varnames"])
}
for i, value := range enum {
if swaggerInteger(value) == 2300 {
if i >= len(enumVarNames) || enumVarNames[i] != "ErrModelInUse" {
t.Fatalf("error code 2300 must align with ErrModelInUse, got names=%v", enumVarNames)
}
return
}
}
t.Fatal("generated Swagger ErrorCode enum does not include model-in-use code 2300")
}
func assertFAQEnabledFilterContract(t *testing.T, data []byte, parse func([]byte, any) error) {
t.Helper()
var spec struct {
Paths map[string]map[string]swaggerOperation `json:"paths" yaml:"paths"`
}
if err := parse(data, &spec); err != nil {
t.Fatalf("parse generated Swagger document: %v", err)
}
faqEntries, ok := spec.Paths["/knowledge-bases/{id}/faq/entries"]
if !ok {
t.Fatal("generated Swagger document does not expose FAQ entries route")
}
getOperation, ok := faqEntries["get"]
if !ok {
t.Fatal("generated Swagger document does not expose GET FAQ entries")
}
for _, parameter := range getOperation.Parameters {
if parameter.Name != "is_enabled" {
continue
}
if parameter.In != "query" || parameter.Type != "boolean" || parameter.Required {
t.Fatalf("is_enabled must be an optional boolean query parameter, got %#v", parameter)
}
return
}
t.Fatal("GET FAQ entries does not document the is_enabled query parameter")
}
func swaggerInteger(value any) int {
switch number := value.(type) {
case int:
return number
case float64:
return int(number)
default:
return 0
}
}
func TestNotificationInboxContract(t *testing.T) {
for _, tt := range swaggerDocuments() {
t.Run(tt.name, func(t *testing.T) {
var spec struct {
Paths map[string]map[string]swaggerOperation `json:"paths" yaml:"paths"`
}
if err := tt.parse(tt.loadSpec(t), &spec); err != nil {
t.Fatal(err)
}
if _, ok := spec.Paths["/notifications/read"]["delete"]; !ok {
t.Fatal("missing clear-read notification endpoint")
}
for _, parameter := range spec.Paths["/notifications"]["get"].Parameters {
if parameter.Name == "cursor" && parameter.In == "query" && parameter.Type == "string" {
return
}
}
t.Fatal("notification listing must document its history cursor")
})
}
}