Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

13.2 KB
Raw Blame
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")
		})
	}
}