3 files changed, 143 insertions, 0 deletions

diff --git a/tests/Cepis.Tests/Fixtures.cs b/tests/Cepis.Tests/Fixtures.cs
index 648f881..a7e69b3 100644
--- a/tests/Cepis.Tests/Fixtures.cs
+++ b/tests/Cepis.Tests/Fixtures.cs
@@ -40,6 +40,30 @@ public static class Fixtures
     public const string NotFound =
         """{"erro":"cep_nao_encontrado","mensagem":"CEP não existe na base do DNE"}""";
 
+    /// <summary>
+    /// The 404 body for a CEP inside a municipality's range. The CEP that draws
+    /// it is 25845000 — the DNE's own start for Areal, and a CEP that was never
+    /// issued.
+    /// </summary>
+    public const string NotFoundWithFaixa = """
+        {"erro":"cep_nao_encontrado","mensagem":"CEP não existe na base do DNE",
+         "faixa":{"localidade":"Areal","uf":"RJ","estado":"Rio de Janeiro",
+                  "regiao":"Sudeste","ibge":"3300225","cep_ini":"25845001",
+                  "cep_fim":"25849899","ceps":118}}
+        """;
+
+    /// <summary>A 404 whose range block is not even an object.</summary>
+    public const string NotFoundBrokenFaixa = """
+        {"erro":"cep_nao_encontrado","mensagem":"CEP não existe na base do DNE",
+         "faixa":"Areal"}
+        """;
+
+    /// <summary>A 404 whose range block names no municipality.</summary>
+    public const string NotFoundNamelessFaixa = """
+        {"erro":"cep_nao_encontrado","mensagem":"CEP não existe na base do DNE",
+         "faixa":{"uf":"RJ","cep_ini":"25845001","cep_fim":"25849899","ceps":118}}
+        """;
+
     /// <summary>The 400 body.</summary>
     public const string InvalidCep =
         """{"erro":"cep_invalido","mensagem":"CEP deve ter 8 dígitos"}""";
diff --git a/tests/Cepis.Tests/LookupTests.cs b/tests/Cepis.Tests/LookupTests.cs
index ad3e2bf..91f1c03 100644
--- a/tests/Cepis.Tests/LookupTests.cs
+++ b/tests/Cepis.Tests/LookupTests.cs
@@ -1,3 +1,5 @@
+using System.Globalization;
+
 namespace Cepis.Tests;
 
 /// <summary>A single lookup: the happy path, the coordinate, and the refusals.</summary>
@@ -120,6 +122,103 @@ public sealed class LookupTests : HttpTestBase
     }
 
     [Fact]
+    public async Task AMissingCepNamesTheMunicipalityItWouldBeIn()
+    {
+        Server.Respond("/25845000", Reply.Of(404, Fixtures.NotFoundWithFaixa));
+
+        var failure = await Assert.ThrowsAsync<CepNotFoundException>(
+            () => Client.LookupAsync("25845000"));
+
+        var faixa = failure.Faixa;
+        Assert.NotNull(faixa);
+        Assert.Equal("Areal", faixa.Localidade);
+        Assert.Equal("RJ", faixa.UF);
+        Assert.Equal("Rio de Janeiro", faixa.Estado);
+        Assert.Equal("Sudeste", faixa.Regiao);
+        Assert.Equal("3300225", faixa.Ibge);
+        Assert.Equal("25845001", faixa.CepIni);
+        Assert.Equal("25849899", faixa.CepFim);
+        Assert.Equal(118, faixa.Ceps);
+    }
+
+    /// <summary>
+    /// The CEP asked for, 25845000, is the DNE's own start for Areal. The range
+    /// reports what exists, so it starts one above — and holds 118 CEPs across
+    /// the ~4,900 numbers it spans, which is why the count travels with it.
+    /// </summary>
+    [Fact]
+    public async Task TheRangeIsWhatExistsAndIsSparse()
+    {
+        Server.Respond("/25845000", Reply.Of(404, Fixtures.NotFoundWithFaixa));
+
+        var failure = await Assert.ThrowsAsync<CepNotFoundException>(
+            () => Client.LookupAsync("25845000"));
+
+        var faixa = failure.Faixa;
+        Assert.NotNull(faixa);
+        Assert.NotEqual("25845000", faixa.CepIni);
+        Assert.True(faixa.Ceps < int.Parse(faixa.CepFim, CultureInfo.InvariantCulture)
+            - int.Parse(faixa.CepIni, CultureInfo.InvariantCulture));
+    }
+
+    [Fact]
+    public async Task TheMessageMentionsTheMunicipality()
+    {
+        Server.Respond("/25845000", Reply.Of(404, Fixtures.NotFoundWithFaixa));
+
+        var failure = await Assert.ThrowsAsync<CepNotFoundException>(
+            () => Client.LookupAsync("25845000"));
+
+        Assert.Contains("25845000", failure.Message, StringComparison.Ordinal);
+        Assert.Contains("Areal/RJ", failure.Message, StringComparison.Ordinal);
+    }
+
+    [Fact]
+    public async Task AMissingCepInNobodysRangeHasNoMunicipality()
+    {
+        Server.Respond("/99999999", Reply.Of(404, Fixtures.NotFound));
+
+        var failure = await Assert.ThrowsAsync<CepNotFoundException>(
+            () => Client.LookupAsync("99999999"));
+
+        Assert.Null(failure.Faixa);
+        Assert.Equal("CEP 99999999 does not exist in the DNE database", failure.Message);
+    }
+
+    [Fact]
+    public async Task ARangeOfTheWrongShapeIsDropped()
+    {
+        Server.Respond("/25845000", Reply.Of(404, Fixtures.NotFoundBrokenFaixa));
+
+        var failure = await Assert.ThrowsAsync<CepNotFoundException>(
+            () => Client.LookupAsync("25845000"));
+
+        Assert.Null(failure.Faixa);
+    }
+
+    [Fact]
+    public async Task ARangeNamingNoMunicipalityIsDropped()
+    {
+        Server.Respond("/25845000", Reply.Of(404, Fixtures.NotFoundNamelessFaixa));
+
+        var failure = await Assert.ThrowsAsync<CepNotFoundException>(
+            () => Client.LookupAsync("25845000"));
+
+        Assert.Null(failure.Faixa);
+    }
+
+    [Fact]
+    public async Task AnUnreadable404BodyIsStillJustANotFound()
+    {
+        Server.Respond("/25845000", Reply.Of(404, "<html><body>gateway</body></html>"));
+
+        var failure = await Assert.ThrowsAsync<CepNotFoundException>(
+            () => Client.LookupAsync("25845000"));
+
+        Assert.Null(failure.Faixa);
+    }
+
+    [Fact]
     public async Task A400CarriesTheApiMessage()
     {
         Server.Respond("/00000000", Reply.Of(400, Fixtures.InvalidCep));
diff --git a/tests/Cepis.Tests/ModelTests.cs b/tests/Cepis.Tests/ModelTests.cs
index 7d9d0d6..f53ecb7 100644
--- a/tests/Cepis.Tests/ModelTests.cs
+++ b/tests/Cepis.Tests/ModelTests.cs
@@ -59,6 +59,26 @@ public sealed class ModelTests
     }
 
     [Fact]
+    public void ARangeDefaultsToTheEmptyStringToo()
+    {
+        var faixa = new Faixa();
+
+        Assert.Equal("", faixa.Localidade);
+        Assert.Equal("", faixa.CepIni);
+        Assert.Equal("", faixa.CepFim);
+        Assert.Equal(0, faixa.Ceps);
+    }
+
+    [Fact]
+    public void ANotFoundCarriesNoRangeUnlessTheApiNamedOne()
+    {
+        Assert.Null(new CepNotFoundException("nope").Faixa);
+        Assert.Equal(
+            "Areal",
+            new CepNotFoundException("nope", new Faixa { Localidade = "Areal" }).Faixa?.Localidade);
+    }
+
+    [Fact]
     public void HealthIsOkOnlyForTheDocumentedStatus()
     {
         Assert.True(new Health { Status = "ok" }.Ok);