lutaml-model 0.8.22 → 0.8.24

data/spec/lutaml/json/adapter/standard_adapter_spec.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "lutaml/json/adapter/standard_adapter"
+
+RSpec.describe Lutaml::Json::Adapter::StandardAdapter do
+  let(:attributes) { { "name" => "John", "age" => 30 } }
+
+  describe ".parse" do
+    # json 3.0 removed create_additions and now raises ArgumentError on any
+    # unknown keyword, so the parser must be called without it.
+    it "parses without passing removed generator keywords to the json gem" do
+      expect(described_class.parse('{"name":"John","age":30}'))
+        .to eq(attributes)
+    end
+  end
+
+  describe "#to_json" do
+    subject(:document) { described_class.new(attributes) }
+
+    it "serializes with no options" do
+      expect(document.to_json).to eq('{"name":"John","age":30}')
+    end
+
+    # :register and :pretty are LutaML's own options. json 2.x ignored unknown
+    # options; json 3.0 raises ArgumentError, so they must be stripped before
+    # they reach JSON.generate.
+    it "strips LutaML options that the json generator does not accept" do
+      expect(document.to_json(register: :default_register))
+        .to eq('{"name":"John","age":30}')
+    end
+
+    it "strips LutaML options when generating pretty output" do
+      expect(document.to_json(pretty: true, register: :default_register))
+        .to eq(%({\n  "name": "John",\n  "age": 30\n}))
+    end
+
+    # An ALLOWLIST and a denylist of LutaML's own option names behave
+    # identically for :register and :pretty. Only a key nobody enumerated
+    # tells them apart -- and json 3.0 raises on it.
+    it "strips a caller option nobody enumerated" do
+      expect(document.to_json(some_unknown_option: 1))
+        .to eq('{"name":"John","age":30}')
+    end
+
+    # json 3.0 removed :escape_slash. Dropping it would silently stop escaping
+    # slashes; it is the old alias of :script_safe, so it is translated.
+    it "honours escape_slash on every json version" do
+      expect(described_class.new({ "a" => "x/y" }).to_json(escape_slash: true))
+        .to eq('{"a":"x\\/y"}')
+    end
+
+    # The filter is an allowlist, not a passthrough: genuine generator options
+    # must still reach JSON.generate.
+    it "forwards options the json generator does accept" do
+      expect(document.to_json(register: :default_register, space: " "))
+        .to eq('{"name": "John","age": 30}')
+    end
+  end
+
+  describe "nesting inside another JSON.generate call" do
+    subject(:document) { described_class.new(attributes) }
+
+    # Ruby's generator hands #to_json a JSON::State, not an options hash.
+    # json 3.0 removed JSON::State#[], so reading :pretty off it raises.
+    it "serializes when nested in a Hash passed to JSON.generate" do
+      expect(JSON.generate({ "doc" => document }))
+        .to eq('{"doc":{"name":"John","age":30}}')
+    end
+
+    it "serializes when nested in an Array passed to JSON.generate" do
+      expect(JSON.generate([document])).to eq('[{"name":"John","age":30}]')
+    end
+
+    # A DEFAULT state renders compact, which is also what a DISCARDED state
+    # produces, so the two examples above cannot tell them apart. These carry
+    # formatting, so dropping the state changes the output.
+    it "inherits the outer indent when nested in a pretty Hash" do
+      expect(JSON.pretty_generate({ "doc" => document }))
+        .to eq(%({\n  "doc": {\n    "name": "John",\n    "age": 30\n  }\n}))
+    end
+
+    it "inherits the outer indent when nested in a pretty Array" do
+      expect(JSON.pretty_generate([document]))
+        .to eq(%([\n  {\n    "name": "John",\n    "age": 30\n  }\n]))
+    end
+
+    it "honours a configured JSON::State handed to #to_json directly" do
+      # A DEFAULT state renders compact, which is also what a discarded state
+      # produces -- so the state has to carry formatting for this to mean
+      # anything.
+      state = JSON::State.new(indent: "  ", object_nl: "\n", space: " ")
+      expect(document.to_json(state))
+        .to eq(%({\n  "name": "John",\n  "age": 30\n}))
+    end
+  end
+
+  describe Lutaml::Json::GeneratorOptions do
+    # The derived half of the allowlist reads JSON::State, which Opal's JSON
+    # shim does not define. BASE_PERMITTED is what the filter falls back to
+    # there, so it has to stand on its own.
+    # BASE_PERMITTED is the whole allowlist on Opal, whose JSON shim has no
+    # State class for DERIVED_PERMITTED to read. So it has to stand alone
+    # against the real generator, not merely be a subset of something larger.
+    it "permits only options the running generator actually accepts" do
+      rejected = described_class::BASE_PERMITTED.reject do |key|
+        JSON.generate({ "a" => 1 }, key => nil)
+        true
+      rescue ArgumentError => e
+        # "unknown keyword" means the generator does not know this option at
+        # all. Any other complaint -- a type error about the nil value we
+        # passed -- means it knows the option and only dislikes the value.
+        !e.message.include?("unknown keyword")
+      rescue StandardError
+        true
+      end
+
+      expect(rejected).to eq([])
+    end
+
+    # Opal's JSON shim defines no State class, so DERIVED_PERMITTED is empty
+    # there and the whole module must still load. Asserting that
+    # BASE_PERMITTED contains some symbols does not exercise the guard; only
+    # loading the file with JSON::State absent does.
+    it "loads and still permits the base set when JSON::State is absent" do
+      hide_const("JSON::State")
+
+      mod = Module.new
+      mod.module_eval(
+        File.read(File.expand_path("../../../../lib/lutaml/json/generator_options.rb", __dir__)),
+      )
+      permitted = mod.const_get(:Lutaml).const_get(:Json)
+        .const_get(:GeneratorOptions)::PERMITTED
+
+      expect(permitted).to eq(described_class::BASE_PERMITTED)
+    end
+
+    it "carries the formatting options pretty output depends on" do
+      expect(described_class::BASE_PERMITTED)
+        .to include(:indent, :object_nl, :space, :space_before)
+    end
+
+    it "rejects a non-Hash options argument" do
+      expect(described_class.filter(nil)).to eq({})
+    end
+
+    it "treats nil as LutaML options" do
+      expect(described_class.lutaml_options?(nil)).to be(true)
+    end
+
+    it "treats a Hash as LutaML options" do
+      expect(described_class.lutaml_options?({ pretty: true })).to be(true)
+    end
+
+    it "does not treat a JSON::State as LutaML options" do
+      expect(described_class.lutaml_options?(JSON::State.new)).to be(false)
+    end
+  end
+end

data/spec/lutaml/json/yeptris_adapter_spec.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+begin
+  require "lutaml/json/adapter/yeptris_adapter"
+rescue LoadError
+  # yeptris ships no platform gem here (e.g. Windows): every example skips.
+end
+
+YEPTRIS_AVAILABLE = defined?(Yeptris)
+
+RSpec.describe(YEPTRIS_AVAILABLE ? Lutaml::Json::Adapter::YeptrisAdapter : Object) do
+  before { skip "yeptris is not available on this platform" unless YEPTRIS_AVAILABLE }
+
+  let(:attributes) { { "name" => "John", "age" => 30, "roles" => %w[admin dev] } }
+
+  describe ".parse" do
+    it "parses a JSON document into a hash" do
+      expect(described_class.parse('{"name":"John","age":30,"roles":["admin","dev"]}'))
+        .to eq(attributes)
+    end
+
+    it "parses scalars and nulls like JSON.parse" do
+      expect(described_class.parse('{"a":1.5,"b":null,"c":true,"d":"1e3"}'))
+        .to eq("a" => 1.5, "b" => nil, "c" => true, "d" => "1e3")
+    end
+
+    it "raises on invalid JSON" do
+      expect { described_class.parse("{nope") }
+        .to raise_error(Yeptris::JSON::ParseError)
+    end
+  end
+
+  describe "#to_json" do
+    subject(:document) { described_class.new(attributes) }
+
+    it "serializes via the inherited json generator" do
+      expect(document.to_json)
+        .to eq('{"name":"John","age":30,"roles":["admin","dev"]}')
+    end
+  end
+
+  describe "round trip through a model" do
+    let(:model_class) do
+      Class.new(Lutaml::Model::Serializable) do
+        attribute :name, :string
+        attribute :roles, :string, collection: true
+
+        key_value do
+          map "name", to: :name
+          map "roles", to: :roles
+        end
+      end
+    end
+
+    it "deserializes via the yeptris engine and serializes back" do
+      model = model_class.from_json('{"name":"John","roles":["admin","dev"]}')
+      expect(model.name).to eq("John")
+      expect(model.roles).to eq(%w[admin dev])
+      expect(model_class.from_json(model.to_json).roles).to eq(%w[admin dev])
+    end
+  end
+end

data/spec/lutaml/jsonld/adapter_spec.rb

@@ -43,4 +43,23 @@ RSpec.describe Lutaml::JsonLd::Adapter do
     round_tripped = JSON.parse(result)
     expect(round_tripped).to eq(jsonld_hash.transform_keys(&:to_s))
   end
+
+  describe "a JSON::State handed to #to_jsonld" do
+    subject(:document) { described_class.new({ "@id" => "urn:x", "n" => 1 }) }
+
+    # Ruby's generator only ever calls #to_json, so a state reaches #to_jsonld
+    # only from a direct caller. json 3.0 removed JSON::State#[], so the state
+    # must be forwarded to the payload rather than read as an options hash.
+    it "honours a state that carries formatting" do
+      state = JSON::State.new(indent: "  ", object_nl: "\n", space: " ")
+
+      expect(document.to_jsonld(state))
+        .to eq(%({\n  "@id": "urn:x",\n  "n": 1\n}))
+    end
+
+    it "renders compactly for a default state" do
+      expect(document.to_jsonld(JSON::State.new))
+        .to eq('{"@id":"urn:x","n":1}')
+    end
+  end
 end

data/spec/lutaml/key_value/adapter/toml/teptris_adapter_spec.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "lutaml/key_value/adapter/toml/teptris_adapter"
+begin
+  require "teptris"
+rescue LoadError
+  # teptris is not resolvable here (absent or broken native library):
+  # every example skips.
+end
+
+TEPTRIS_AVAILABLE = defined?(Teptris)
+
+RSpec.describe(TEPTRIS_AVAILABLE ? Lutaml::KeyValue::Adapter::Toml::TeptrisAdapter : Object) do
+  before { skip "teptris is not available" unless TEPTRIS_AVAILABLE }
+
+  describe ".parse" do
+    it "parses a TOML document into a hash" do
+      expect(described_class.parse("name = \"John\"\nage = 30\n"))
+        .to eq("name" => "John", "age" => 30)
+    end
+
+    it "parses nested tables and arrays" do
+      toml = <<~TOML
+        title = "cfg"
+        [owner]
+        name = "t"
+        tags = ["a", "b"]
+      TOML
+      expect(described_class.parse(toml))
+        .to eq("title" => "cfg", "owner" => { "name" => "t", "tags" => %w[a b] })
+    end
+
+    it "materializes dates and datetimes like tomlib" do
+      require "date"
+      doc = described_class.parse("d = 1979-05-27\ndt = 1979-05-27T07:32:00Z\n")
+      expect(doc["d"]).to be_a(Date)
+      expect(doc["dt"]).to be_a(Time)
+    end
+
+    it "reports parse errors with line and column" do
+      expect { described_class.parse("a = [1,") }
+        .to raise_error(Teptris::ParseError) do |e|
+          expect(e.line).to eq(1)
+          expect(e.column).to eq(8)
+        end
+    end
+  end
+
+  describe "#to_toml" do
+    it "dumps a hash to TOML" do
+      attributes = { "name" => "x", "nested" => { "a" => [1, 2] } }
+      expect(described_class.new(attributes).to_toml)
+        .to include("name", "[nested]", "a = [1, 2]")
+    end
+
+    it "unwraps the __root__ KeyValueElement wrapper" do
+      element = Lutaml::KeyValue::DataModel::Element.new("__root__")
+      name_child = Lutaml::KeyValue::DataModel::Element.new("name")
+      name_child.value = "x"
+      element.add_child(name_child)
+      expect(described_class.new(element).to_toml).to include("name")
+    end
+  end
+
+  it "round-trips through the model layer" do
+    attributes = { "name" => "John", "age" => 30 }
+    adapter_toml = described_class.new(attributes).to_toml
+    expect(described_class.parse(adapter_toml)).to eq(attributes)
+  end
+end

data/spec/lutaml/model/collection_spec.rb

@@ -644,7 +644,7 @@ RSpec.describe Lutaml::Model::Collection do
       collection = title_collection_class.from_json(json_data)
 
       # JSON.parse should only be called once on the main array, not on individual strings
-      expect(JSON).to have_received(:parse).once.with(json_data, anything)
+      expect(JSON).to have_received(:parse).once.with(json_data)
       expect(collection.titles.map(&:content)).to eq(["Title One", "Title Two",
                                                       "Title Three"])
     end

data/spec/lutaml/model/collection_state_nesting_spec.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# A Collection overrides #to_format and merges `collection: true` into the
+# options BEFORE the base implementation runs. JSON::State#merge is #configure,
+# which rejects unknown keys on json 3.0, so the state has to be wrapped first.
+RSpec.describe "a collection nested inside JSON.generate" do
+  before do
+    stub_const("NestedItem", Class.new(Lutaml::Model::Serializable) do
+      attribute :n, :string
+    end)
+    stub_const("NestedItems", Class.new(Lutaml::Model::Collection) do
+      instances :items, NestedItem
+    end)
+  end
+
+  let(:collection) { NestedItems.new([NestedItem.new(n: "a")]) }
+
+  it "serializes inside a Hash" do
+    expect(JSON.generate({ "c" => collection })).to eq('{"c":[{"n":"a"}]}')
+  end
+
+  it "inherits the outer indent inside a pretty Hash" do
+    expect(JSON.pretty_generate({ "c" => collection }))
+      .to eq(%({\n  "c": [\n    {\n      "n": "a"\n    }\n  ]\n}))
+  end
+
+  # The class-level entry point normalises separately from the instance one,
+  # and deleting that normaliser leaves every instance example green.
+  it "normalises a state passed to the class-level entry point" do
+    # array_nl is what puts the newlines in an array; without it the state
+    # is not a pretty state at all and the example proves nothing.
+    state = JSON::State.new(indent: "  ", object_nl: "\n", array_nl: "\n",
+                            space: " ")
+
+    expect(NestedItems.to_json(collection, state))
+      .to eq(%([\n  {\n    "n": "a"\n  }\n]))
+  end
+
+  it "still serializes directly" do
+    expect(collection.to_json).to eq('[{"n":"a"}]')
+  end
+end

data/spec/lutaml/model/generator_defaults_spec.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "oj"
+require "multi_json"
+
+# What a nested model should do with the outer generator's options differs per
+# ADAPTER, not per option. Reference values are unmodified main on json 2.21.2.
+#
+#   stdlib  honours script_safe / ascii_only / pretty  -> receives the state
+#   Oj      ignores them and uses its own escape_mode  -> receives none of them
+#
+# Four earlier attempts at this got it wrong by reasoning about option names
+# instead of measuring each adapter, so every row here is a measured cell.
+RSpec.describe "generator options reaching a nested model" do
+  before do
+    stub_const("EscapeProbe", Class.new(Lutaml::Model::Serializable) do
+      attribute :s, :string
+    end)
+  end
+
+  let(:model) { EscapeProbe.new(s: "</script>é") }
+
+  describe "the stdlib adapter" do
+    it "honours script_safe" do
+      expect(JSON.generate({ "m" => model }, script_safe: true))
+        .to eq('{"m":{"s":"<\\/script>é"}}')
+    end
+
+    it "honours ascii_only" do
+      expect(JSON.generate({ "m" => model }, ascii_only: true))
+        .to eq('{"m":{"s":"</script>\\u00e9"}}')
+    end
+
+    it "honours the outer indent" do
+      expect(JSON.pretty_generate({ "m" => model }))
+        .to eq(%({\n  "m": {\n    "s": "</script>é"\n  }\n}))
+    end
+  end
+
+  describe "the Oj adapter" do
+    around do |example|
+      previous = Oj.default_options
+      Oj.default_options = { escape_mode: :xss_safe }
+      example.run
+      Oj.default_options = previous
+    end
+
+    # Oj must keep its OWN escaping. Forwarding the generator's options -- all
+    # of them, only the caller-set ones, or just ascii_only -- each reset
+    # escape_mode and silently emitted a literal </script>.
+    it "keeps its configured escape_mode when no option is passed" do
+      result = Lutaml::Model::Config.with_adapter(json: :oj) do
+        JSON.generate({ "m" => model })
+      end
+
+      expect(result).to eq('{"m":{"s":"\\u003c\\/script\\u003e\\u00e9"}}')
+    end
+
+    it "keeps its configured escape_mode when ascii_only is passed" do
+      result = Lutaml::Model::Config.with_adapter(json: :oj) do
+        JSON.generate({ "m" => model }, ascii_only: true)
+      end
+
+      expect(result).to eq('{"m":{"s":"\\u003c\\/script\\u003e\\u00e9"}}')
+    end
+
+    it "keeps its configured escape_mode when script_safe is passed" do
+      result = Lutaml::Model::Config.with_adapter(json: :oj) do
+        JSON.generate({ "m" => model }, script_safe: true)
+      end
+
+      expect(result).to eq('{"m":{"s":"\\u003c\\/script\\u003e\\u00e9"}}')
+    end
+  end
+
+  # MultiJson's json_gem backend IS the stdlib generator, so unlike Oj it does
+  # honour these options and must still receive them. That BACKEND cannot run
+  # under json 3.0 -- it sends create_additions, which json removed -- so these
+  # are asserted on the versions where it works. multi_json itself is fine
+  # under json 3.0 on its Oj backend; only json_gem is affected.
+  describe "the MultiJson adapter", if: Gem::Version.new(JSON::VERSION) < Gem::Version.new("3.0.0") do
+    before { MultiJson.use(:json_gem) }
+
+    it "still receives script_safe" do
+      result = Lutaml::Model::Config.with_adapter(json: :multi_json) do
+        JSON.generate({ "m" => model }, script_safe: true)
+      end
+
+      expect(result).to eq('{"m":{"s":"<\\/script>é"}}')
+    end
+
+    it "still receives ascii_only" do
+      result = Lutaml::Model::Config.with_adapter(json: :multi_json) do
+        JSON.generate({ "m" => model }, ascii_only: true)
+      end
+
+      expect(result).to eq('{"m":{"s":"</script>\\u00e9"}}')
+    end
+  end
+end

data/spec/lutaml/model/json_adapter_spec.rb

@@ -1,4 +1,5 @@
 require "spec_helper"
+require "multi_json"
 require "lutaml/key_value/adapter/json/standard_adapter"
 require "lutaml/key_value/adapter/json/multi_json_adapter"
 require "lutaml/key_value/adapter/json/oj_adapter"
@@ -37,6 +38,11 @@ RSpec.describe "JsonAdapter" do
   end
 
   describe Lutaml::KeyValue::Adapter::Json::MultiJsonAdapter do
+    # multi_json 1.21's json_gem adapter passes options positionally to
+    # JSON.parse, which json >= 3 removed (intridea/multi_json#227).
+    if Gem::Version.new(JSON::VERSION) >= Gem::Version.new("3")
+      before { skip "multi_json is incompatible with json #{JSON::VERSION} (intridea/multi_json#227)" }
+    end
     it_behaves_like "a JSON adapter", described_class
   end
 

data/spec/lutaml/model/json_state_nesting_spec.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# json 3.0 removed JSON::State#[]. Ruby's generator passes a JSON::State to
+# #to_json whenever a model is nested inside another JSON.generate call, so the
+# model layer must not read option keys off it.
+RSpec.describe "a model nested inside JSON.generate" do
+  before do
+    stub_const("JsonStateNestingModel", Class.new(Lutaml::Model::Serializable) do
+      attribute :name, :string
+      attribute :age, :integer
+    end)
+  end
+
+  let(:model) { JsonStateNestingModel.new(name: "John", age: 30) }
+
+  it "serializes inside a Hash" do
+    expect(JSON.generate({ "person" => model }))
+      .to eq('{"person":{"name":"John","age":30}}')
+  end
+
+  it "serializes inside an Array" do
+    expect(JSON.generate([model])).to eq('[{"name":"John","age":30}]')
+  end
+
+  # The generator's JSON::State carries the surrounding indent context. It has
+  # to reach the adapter, not be discarded, or a nested model silently renders
+  # compact inside an otherwise pretty document. Reference values are the
+  # output of unmodified main on json 2.20.0.
+  it "inherits the surrounding indent inside a pretty Hash" do
+    expect(JSON.pretty_generate({ "person" => model }))
+      .to eq(%({\n  "person": {\n    "name": "John",\n    "age": 30\n  }\n}))
+  end
+
+  it "inherits the surrounding indent inside a pretty Array" do
+    expect(JSON.pretty_generate([model]))
+      .to eq(%([\n  {\n    "name": "John",\n    "age": 30\n  }\n]))
+  end
+
+  it "still honours LutaML's own options when called directly" do
+    expect(model.to_json(pretty: true))
+      .to eq(%({\n  "name": "John",\n  "age": 30\n}))
+  end
+
+  # A non-Hash options argument must be replaced, not merely captured -- a
+  # falsy one (nil, false) previously stayed in place and the next line called
+  # .delete on it.
+  it "does not raise on a nil options argument" do
+    expect(model.to_json(nil)).to eq('{"name":"John","age":30}')
+  end
+
+  it "does not raise on a false options argument" do
+    expect(model.to_json(false)).to eq('{"name":"John","age":30}')
+  end
+
+  # A non-Hash options argument reaches every format, not just JSON, so the
+  # normalisation must not skip format-specific validation on the way past.
+  # A type-only model has no root mapping and must refuse to serialise alone.
+  it "still applies XML root validation to a non-Hash argument" do
+    stub_const("TypeOnlyModel", Class.new(Lutaml::Model::Serializable) do
+      attribute :n, :string
+    end)
+
+    expect { TypeOnlyModel.new(n: "a").to_xml(nil) }
+      .to raise_error(Lutaml::Model::TypeOnlyMappingError)
+  end
+
+  # Every example above goes through an INSTANCE entry point. The class-level
+  # one normalises separately, and deleting that normaliser leaves them all
+  # green.
+  it "normalises a state passed to the class-level entry point" do
+    state = JSON::State.new(indent: "  ", object_nl: "\n", space: " ")
+
+    expect(JsonStateNestingModel.to_json(model, state))
+      .to eq(%({\n  "name": "John",\n  "age": 30\n}))
+  end
+
+  it "leaves non-JSON formats untouched" do
+    expect(model.to_yaml).to eq("---\nname: John\nage: 30\n")
+  end
+end

data/spec/lutaml/model/toml_adapter_spec.rb

@@ -17,6 +17,8 @@ RSpec.describe "TomlAdapter" do
         TomlRB.dump(attributes)
       elsif adapter_class == Lutaml::Model::Toml::TomlibAdapter
         Tomlib.dump(attributes)
+      elsif adapter_class == Lutaml::Model::Toml::TeptrisAdapter && defined?(Teptris)
+        Teptris::TOML.dump(attributes)
       end
     end
 
@@ -45,4 +47,10 @@ RSpec.describe "TomlAdapter" do
       it_behaves_like "a TOML adapter", described_class
     end
   end
+
+  if defined?(Teptris)
+    describe Lutaml::Model::Toml::TeptrisAdapter do
+      it_behaves_like "a TOML adapter", described_class
+    end
+  end
 end

data/spec/lutaml/model/toml_spec.rb

@@ -10,7 +10,7 @@ RSpec.describe Lutaml::Model::Toml do
     end
 
     it "does not autoload native TOML adapters on Opal" do
-      %i[TomlRbAdapter TomlibAdapter].each do |constant_name|
+      %i[TomlRbAdapter TomlibAdapter TeptrisAdapter].each do |constant_name|
         hide_const("Lutaml::Toml::Adapter::#{constant_name}")
       end
 
@@ -19,12 +19,14 @@ RSpec.describe Lutaml::Model::Toml do
 
       expect(Lutaml::Toml::Adapter.autoload?(:TomlRbAdapter)).to be_nil
       expect(Lutaml::Toml::Adapter.autoload?(:TomlibAdapter)).to be_nil
+      expect(Lutaml::Toml::Adapter.autoload?(:TeptrisAdapter)).to be_nil
     end
   end
 
   describe ".detect_toml_adapter" do
     before do
       # Hide any existing constants first
+      hide_const("Teptris") if Object.const_defined?(:Teptris)
       hide_const("Tomlib") if Object.const_defined?(:Tomlib)
       hide_const("TomlRb") if Object.const_defined?(:TomlRb)
 
@@ -32,6 +34,39 @@ RSpec.describe Lutaml::Model::Toml do
       allow(Lutaml::Model::Utils).to receive(:require).and_return(true)
     end
 
+    context "when teptris is available" do
+      before do
+        stub_const("Teptris", Module.new)
+      end
+
+      it "returns :teptris on non-Windows platforms (tomlib absent)" do
+        allow(Gem).to receive(:win_platform?).and_return(false)
+        expect(described_class.detect_toml_adapter).to eq(:teptris)
+      end
+
+      it "returns :teptris on Windows (native TOML without tomlib segfaults)" do
+        allow(Gem).to receive(:win_platform?).and_return(true)
+        expect(described_class.detect_toml_adapter).to eq(:teptris)
+      end
+    end
+
+    context "when teptris and tomlib are both available" do
+      before do
+        stub_const("Teptris", Module.new)
+        stub_const("Tomlib", Module.new)
+      end
+
+      it "prefers teptris on non-Windows (0.2.12+ beats tomlib both directions)" do
+        allow(Gem).to receive(:win_platform?).and_return(false)
+        expect(described_class.detect_toml_adapter).to eq(:teptris)
+      end
+
+      it "prefers teptris on Windows" do
+        allow(Gem).to receive(:win_platform?).and_return(true)
+        expect(described_class.detect_toml_adapter).to eq(:teptris)
+      end
+    end
+
     context "when Tomlib is available" do
       before do
         stub_const("Tomlib", Module.new)