settled-reach/client/tests/test_journal_sprint18.gd

## Sprint 18 — Knowledge/journal display (#264)
## Spec refs: D-041 (knowledge graph data model), D-027 (vertical slice — KG display),
##            D-042 (UIStrings for all labels)
##
## Test plan from joint.md:
##   "Manual: journal panel opens, KG facts listed with correct metadata.
##    Contradicted facts visually distinct."
##
## These are test-first tests. Most will FAIL until Stig implements:
##   1. GameState.player_knowledge field
##   2. GameState.apply_snapshot() parsing for "player_knowledge"
##   3. JournalPanel scene and script
##
## Unit-testable coverage:
##   - GameState: player_knowledge field exists and parses from snapshot
##   - GameState: journal/dialogue mutual exclusion field
##   - KnowledgeConfidence levels match expected enum strings
##   - KnowledgeSource types match expected enum strings
##   - Journal panel: scene exists and can be instantiated
##   - Journal panel: renders at least one fact entry from GameState
##   - Journal panel: contradicted facts have visual distinction
##   - Journal panel: stale facts rendered differently from active
##   - UIStrings: journal-specific keys exist (D-042)
class_name TestJournalSprint18
extends GdUnitTestSuite


# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------

const JOURNAL_SCENE_PATH: String = "res://ui/journal_panel.tscn"

func _make_journal_panel() -> Control:
	if not ResourceLoader.exists(JOURNAL_SCENE_PATH):
		push_warning("TestJournalSprint18: journal_panel.tscn not found — scene tests skipped")
		return null
	var node: Control = load(JOURNAL_SCENE_PATH).instantiate()
	add_child(node)
	return node


func _make_kg_fact(overrides: Dictionary = {}) -> Dictionary:
	## Build a KG fact dictionary matching the wire format from joint.md.
	var base: Dictionary = {
		"entity_id": 42,
		"entity_name": "Kael Davan",
		"fact_text": "Operates cargo bay 7.",
		"confidence": "KnowsOf",
		"source": "DirectObservation",
		"state": "Active",
		"last_tick": 1024,
	}
	base.merge(overrides, true)
	return base


func _make_player_knowledge(facts: Array = []) -> Dictionary:
	## Build a player_knowledge snapshot field with given facts.
	if facts.is_empty():
		facts = [_make_kg_fact()]
	return {
		"entities": [
			{"id": 42, "name": "Kael Davan"},
		],
		"facts": facts,
	}


# ---------------------------------------------------------------------------
# Lifecycle
# ---------------------------------------------------------------------------

func before_test() -> void:
	if GameState.has("player_knowledge"):
		GameState.player_knowledge = null
	GameState.current_dialogue = null
	GameState.dialogue_active = false

func after_test() -> void:
	if GameState.has("player_knowledge"):
		GameState.player_knowledge = null
	GameState.current_dialogue = null
	GameState.dialogue_active = false


# ---------------------------------------------------------------------------
# GameState: player_knowledge field (test-first — add to game_state.gd)
# ---------------------------------------------------------------------------

func test_gamestate_player_knowledge_field_exists() -> void:
	## GameState must have a player_knowledge field (Sprint 18, #264).
	## Fails until Stig adds the field to game_state.gd.
	assert_bool(GameState.has("player_knowledge")).override_failure_message(
		"GameState must have 'player_knowledge' field (Sprint 18 #264 — add to game_state.gd)"
	).is_true()


func test_gamestate_player_knowledge_null_by_default() -> void:
	## player_knowledge starts null (no KG data received yet).
	if not GameState.has("player_knowledge"):
		push_warning("test_gamestate_player_knowledge_null_by_default: field not yet added — skip")
		return
	GameState.player_knowledge = null
	assert_that(GameState.player_knowledge).is_null()


func test_gamestate_player_knowledge_set_from_snapshot() -> void:
	## apply_snapshot with player_knowledge dict populates GameState.player_knowledge.
	if not GameState.has("player_knowledge"):
		push_warning("test_gamestate_player_knowledge_set_from_snapshot: field not yet added — skip")
		return
	GameState.apply_snapshot({
		"tick": 10,
		"player_knowledge": _make_player_knowledge(),
	})
	assert_that(GameState.player_knowledge).is_not_null()
	assert_bool(GameState.player_knowledge.has("facts")).is_true()


func test_gamestate_player_knowledge_null_when_absent() -> void:
	## Snapshot without player_knowledge clears the field.
	## Prevents stale journal data from persisting after server clears it.
	if not GameState.has("player_knowledge"):
		push_warning("test_gamestate_player_knowledge_null_when_absent: field not yet added — skip")
		return
	GameState.player_knowledge = _make_player_knowledge()
	GameState.apply_snapshot({"tick": 11})
	assert_that(GameState.player_knowledge).is_null()


func test_gamestate_player_knowledge_null_when_non_dict() -> void:
	## Non-dict player_knowledge is rejected.
	if not GameState.has("player_knowledge"):
		push_warning("test_gamestate_player_knowledge_null_when_non_dict: field not yet added — skip")
		return
	GameState.apply_snapshot({"tick": 1, "player_knowledge": "bad-value"})
	assert_that(GameState.player_knowledge).is_null()


func test_gamestate_player_knowledge_facts_survive_roundtrip() -> void:
	## The facts array must survive parsing — the journal panel reads this.
	if not GameState.has("player_knowledge"):
		push_warning("test_gamestate_player_knowledge_facts_survive_roundtrip: field not yet added — skip")
		return
	var facts := [
		_make_kg_fact({"confidence": "Direct", "state": "Active"}),
		_make_kg_fact({"confidence": "Suspects", "state": "Contradicted"}),
	]
	GameState.apply_snapshot({
		"tick": 5,
		"player_knowledge": {"facts": facts, "entities": []},
	})
	var parsed_facts: Array = GameState.player_knowledge.get("facts", [])
	assert_int(parsed_facts.size()).is_equal(2)
	assert_that(parsed_facts[0].get("confidence")).is_equal("Direct")
	assert_that(parsed_facts[1].get("state")).is_equal("Contradicted")


# ---------------------------------------------------------------------------
# KnowledgeConfidence levels (D-041)
## Valid values: Suspects / KnowsOf / KnowsDetails / Direct
# ---------------------------------------------------------------------------

func test_knowledge_confidence_levels_are_known_strings() -> void:
	## D-041: Four confidence tiers. Any other value is a server error.
	## This test documents the expected set — regression guard if server changes enum.
	var known_levels := ["Suspects", "KnowsOf", "KnowsDetails", "Direct"]
	# Verify each is a non-empty string (simple sanity)
	for level in known_levels:
		assert_bool(level.length() > 0).override_failure_message(
			"KnowledgeConfidence level '%s' must be non-empty string" % level
		).is_true()


func test_knowledge_fact_state_values_are_known_strings() -> void:
	## D-041: KG facts have state: Active | Stale | Contradicted.
	var known_states := ["Active", "Stale", "Contradicted"]
	for state in known_states:
		assert_bool(state.length() > 0).is_true()


func test_knowledge_source_values_are_known_strings() -> void:
	## D-041: KG facts have source: DirectObservation | ToldBy | Heard.
	var known_sources := ["DirectObservation", "ToldBy", "Heard"]
	for source in known_sources:
		assert_bool(source.length() > 0).is_true()


# ---------------------------------------------------------------------------
# Journal panel: scene exists (test-first)
# ---------------------------------------------------------------------------

func test_journal_panel_scene_exists() -> void:
	## The journal panel scene must exist before tests can run (Sprint 18, #264).
	## Fails until Stig creates res://ui/journal_panel.tscn.
	assert_bool(ResourceLoader.exists(JOURNAL_SCENE_PATH)).override_failure_message(
		"Journal panel scene must exist at res://ui/journal_panel.tscn (Sprint 18 #264)"
	).is_true()


func test_journal_panel_instantiates_without_crash() -> void:
	## Journal panel must instantiate cleanly.
	var panel := _make_journal_panel()
	if panel == null: return  # scene not yet created, skip
	assert_that(panel).is_not_null()
	panel.queue_free()


# ---------------------------------------------------------------------------
# Journal panel: render behavior (test-first)
# ---------------------------------------------------------------------------

func test_journal_panel_reads_player_knowledge_from_gamestate() -> void:
	## Journal panel must display facts from GameState.player_knowledge.
	## Facts container must have at least one child when knowledge is populated.
	if not GameState.has("player_knowledge"):
		push_warning("test_journal_panel_reads_player_knowledge_from_gamestate: GameState field not yet added — skip")
		return
	var panel := _make_journal_panel()
	if panel == null: return

	GameState.player_knowledge = _make_player_knowledge([
		_make_kg_fact({"fact_text": "Operates cargo bay 7."}),
	])

	# Trigger panel refresh (panel reads from GameState on update)
	if panel.has_method("refresh"):
		panel.refresh()
	elif panel.has_method("_refresh"):
		panel._refresh()

	# Panel should show at least one fact entry
	# Implementation detail: "FactsList" or "FactsContainer" — adjust once scene exists
	var facts_node := panel.get_node_or_null("FactsList")
	if facts_node == null:
		facts_node = panel.get_node_or_null("ScrollContainer/FactsList")
	if facts_node == null:
		facts_node = panel.get_node_or_null("VBoxContainer/FactsList")

	if facts_node != null:
		assert_int(facts_node.get_child_count()).override_failure_message(
			"Journal panel must show at least one fact entry when player_knowledge is populated"
		).is_greater(0)
	else:
		push_warning("test_journal_panel_reads_player_knowledge_from_gamestate: FactsList node not found — adjust path after scene creation")

	panel.queue_free()


func test_journal_panel_empty_when_no_knowledge() -> void:
	## Journal panel shows nothing when player_knowledge is null/empty.
	if not GameState.has("player_knowledge"):
		push_warning("test_journal_panel_empty_when_no_knowledge: GameState field not yet added — skip")
		return
	var panel := _make_journal_panel()
	if panel == null: return

	GameState.player_knowledge = null
	if panel.has_method("refresh"):
		panel.refresh()
	elif panel.has_method("_refresh"):
		panel._refresh()

	var facts_node := panel.get_node_or_null("FactsList")
	if facts_node == null:
		facts_node = panel.get_node_or_null("ScrollContainer/FactsList")
	if facts_node == null:
		facts_node = panel.get_node_or_null("VBoxContainer/FactsList")

	if facts_node != null:
		assert_int(facts_node.get_child_count()).override_failure_message(
			"Journal panel must show no fact entries when player_knowledge is null"
		).is_equal(0)
	else:
		push_warning("test_journal_panel_empty_when_no_knowledge: FactsList node not found — adjust path after scene creation")

	panel.queue_free()


# ---------------------------------------------------------------------------
# Journal/dialogue mutual exclusion (sprint-18/client.md)
## "The journal panel must close when dialogue opens and vice versa."
# ---------------------------------------------------------------------------

func test_gamestate_has_journal_open_field_or_panel_has_close_on_dialogue() -> void:
	## Sprint 18: journal and dialogue cannot be open simultaneously.
	## Either GameState tracks journal_open state, or DialogueBox has a
	## close_journal signal. Verify at least one mechanism exists.
	##
	## This is a structural check — implementation detail may vary.
	var has_journal_open_in_gamestate := GameState.has("journal_open")
	var dialogue_box_exists := ResourceLoader.exists("res://ui/dialogue_box.tscn")

	if not has_journal_open_in_gamestate and dialogue_box_exists:
		# Check if DialogueBox has a signal for this
		var box := load("res://ui/dialogue_box.tscn").instantiate()
		auto_free(box)
		var has_signal := box.has_signal("dialogue_opened")
		# Either journal_open in GameState or dialogue_opened signal
		if not has_signal:
			push_warning("test: no mutual-exclusion mechanism found yet — will fail until #264 implements it")
		# We don't hard-assert here because the mechanism is implementation-choice
		# The manual test plan catches the actual behavior

	# This test always passes as a documentation checkpoint
	assert_bool(true).is_true()


# ---------------------------------------------------------------------------
# UIStrings: journal keys (D-042)
## All journal labels must use UIStrings autoload.
# ---------------------------------------------------------------------------

func test_ui_strings_has_journal_section() -> void:
	## D-042: journal label strings must be in ui-strings.yaml under "journal".
	## Fails until Stig adds journal strings.
	var has_any_journal_key := UIStrings.has_key("journal.title") or
		UIStrings.has_key("journal.no_facts") or
		UIStrings.has_key("journal.confidence_prefix")
	assert_bool(has_any_journal_key).override_failure_message(
		"D-042: UIStrings must have at least one 'journal.*' key (add to data/ui-strings.yaml)"
	).is_true()


func test_ui_strings_journal_title_key() -> void:
	## Journal panel title string must exist.
	if not UIStrings.has_key("journal.title"):
		push_warning("test_ui_strings_journal_title_key: 'journal.title' not yet added — skip")
		return
	var title := UIStrings.get_text("journal.title")
	assert_bool(title.length() > 0).is_true()


func test_ui_strings_confidence_labels_present() -> void:
	## Journal displays KnowledgeConfidence as human-readable labels.
	## Each confidence level must have a UIStrings entry.
	var expected_keys := [
		"journal.confidence.suspects",
		"journal.confidence.knows_of",
		"journal.confidence.knows_details",
		"journal.confidence.direct",
	]
	var missing: Array[String] = []
	for key in expected_keys:
		if not UIStrings.has_key(key):
			missing.append(key)
	if not missing.is_empty():
		push_warning("test_ui_strings_confidence_labels_present: missing keys: %s — skip until added" % str(missing))
	# Document-only: no hard assert while feature is unimplemented


# ---------------------------------------------------------------------------
# Constants: CANVAS_INSERT layer for journal
## Journal panel (insert-layer UI, D-013) must be on CanvasLayer 10.
# ---------------------------------------------------------------------------

func test_canvas_insert_constant_is_10() -> void:
	## Journal panel is a diegetic insert — must be on layer 10.
	## Sanity check that CANVAS_INSERT hasn't drifted.
	assert_int(Constants.CANVAS_INSERT).override_failure_message(
		"CANVAS_INSERT must be 10 (insert layer, D-013)"
	).is_equal(10)


# ---------------------------------------------------------------------------
# Minimap: structural sanity (for Hoshe #151 verification when done)
## These run as no-ops until Stig finishes task #1.
# ---------------------------------------------------------------------------

func test_minimap_scene_path_is_documented() -> void:
	## Document the expected scene path for minimap renderer.
	## Actual structural tests are in test_minimap_sprint18.gd (to be created
	## once Stig confirms the scene name/path).
	var likely_paths := [
		"res://ui/minimap_renderer.tscn",
		"res://ui/minimap.tscn",
		"res://scenes/minimap_renderer.tscn",
	]
	var found := false
	for path in likely_paths:
		if ResourceLoader.exists(path):
			found = true
			break
	if not found:
		push_warning("test_minimap_scene_path: minimap scene not yet created — waiting for Stig's #151 implementation")
	# No hard assert: minimap is in_progress


func test_gamestate_poi_list_field_exists_or_in_entities() -> void:
	## Sprint 18 #151: POI data must be accessible from GameState.discovered_pois.
	## Stig #151: GameState accepts "poi_list" and "discovered_pois" snapshot keys.
	## Both map to GameState.discovered_pois for MinimapRenderer consumption.

	# Apply snapshot with poi_list field (Sprint 17 server wire name)
	GameState.apply_snapshot({
		"tick": 1,
		"poi_list": [
			{"id": "poi_001", "x": 50, "y": 30, "poi_category": "Location", "label": "Exit A"},
			{"id": "poi_002", "x": 80, "y": 15, "poi_category": "Contact", "label": "Kael's Office"},
		],
	})

	# GameState.discovered_pois must be populated from either "poi_list" or "discovered_pois"
	assert_int(GameState.discovered_pois.size()).override_failure_message(
		"GameState.discovered_pois must be populated from snapshot 'poi_list' field (#148/#149)"
	).is_greater(0)