feat: complete Phase 3 with circular reference tests and documentation (#75)

- Add circular reference handling tests for InclusionMapper
- Add filtered includes + pagination integration tests
- Update upgrade-guide.md with v1.5.0 test coverage details
- Add contributing.md with test patterns and development workflow
- Mark Phase 3 complete in roadmap

Author: erlendellefsen

JsonApiToolkit.Tests/Integration/JsonApiQueryAsyncTests.cs

@@ -855,6 +855,127 @@ public async Task GetArticles_PageSizeLargerThanDataset_ReturnsAllAsync()
 
     #endregion
 
+    #region Filtered Includes with Pagination Tests
+
+    [Fact]
+    public async Task GetArticles_FilteredIncludesWithPagination_ReturnsCorrectDataAsync()
+    {
+        // Filter on included resource + pagination
+        var response = await _client.GetAsync(
+            "/api/articles?filter[author.name]=Alice&include=author&page[number]=1&page[size]=2&sort=id"
+        );
+
+        Assert.Equal(HttpStatusCode.OK, response.StatusCode);
+
+        var content = await response.Content.ReadAsStringAsync();
+        var document = JsonSerializer.Deserialize<JsonApiCollectionDocument<ResourceObject>>(
+            content,
+            _jsonOptions
+        );
+
+        Assert.NotNull(document?.Data);
+        // Alice has 2 articles (ids 1 and 2), page size 2 should return both
+        Assert.Equal(2, document.Data.Count());
+
+        // Verify pagination metadata reflects filtered count
+        Assert.NotNull(document.Meta);
+        Assert.Equal(2, GetPaginationValue<int>(document.Meta, "totalResources"));
+        Assert.Equal(1, GetPaginationValue<int>(document.Meta, "totalPages"));
+
+        // Verify included author is Alice
+        Assert.NotNull(document.Included);
+        Assert.Single(document.Included);
+        Assert.Equal("Alice", document.Included.First().Attributes?["name"]?.ToString());
+    }
+
+    [Fact]
+    public async Task GetArticles_FilteredIncludesWithPaginationSecondPage_ReturnsCorrectDataAsync()
+    {
+        // Filter to published articles, include author, get second page
+        var response = await _client.GetAsync(
+            "/api/articles?filter[isPublished]=true&include=author&page[number]=2&page[size]=2&sort=id"
+        );
+
+        Assert.Equal(HttpStatusCode.OK, response.StatusCode);
+
+        var content = await response.Content.ReadAsStringAsync();
+        var document = JsonSerializer.Deserialize<JsonApiCollectionDocument<ResourceObject>>(
+            content,
+            _jsonOptions
+        );
+
+        Assert.NotNull(document?.Data);
+        // 4 published articles, page 2 with size 2 should return 2 articles
+        Assert.Equal(2, document.Data.Count());
+
+        // Verify pagination
+        Assert.NotNull(document.Meta);
+        Assert.Equal(4, GetPaginationValue<int>(document.Meta, "totalResources"));
+        Assert.Equal(2, GetPaginationValue<int>(document.Meta, "totalPages"));
+        Assert.Equal(2, GetPaginationValue<int>(document.Meta, "currentPage"));
+
+        // Verify includes are present
+        Assert.NotNull(document.Included);
+        Assert.NotEmpty(document.Included);
+    }
+
+    [Fact]
+    public async Task GetArticles_MultipleIncludesWithFilterAndPagination_ReturnsAllIncludedAsync()
+    {
+        // Complex query: filter + multiple includes + pagination
+        var response = await _client.GetAsync(
+            "/api/articles?filter[viewCount][ge]=50&include=author,comments&page[number]=1&page[size]=3&sort=-viewCount"
+        );
+
+        Assert.Equal(HttpStatusCode.OK, response.StatusCode);
+
+        var content = await response.Content.ReadAsStringAsync();
+        var document = JsonSerializer.Deserialize<JsonApiCollectionDocument<ResourceObject>>(
+            content,
+            _jsonOptions
+        );
+
+        Assert.NotNull(document?.Data);
+        // viewCount >= 50: articles with 50, 75, 100, 200 = 4 articles, page size 3
+        Assert.Equal(3, document.Data.Count());
+
+        // Verify sorted by viewCount descending
+        var ids = document.Data.Select(r => r.Id).ToList();
+        Assert.Equal("4", ids[0]); // viewCount: 200
+        Assert.Equal("1", ids[1]); // viewCount: 100
+        Assert.Equal("5", ids[2]); // viewCount: 75
+
+        // Verify includes contain both authors and comments
+        Assert.NotNull(document.Included);
+        Assert.Contains(document.Included, r => r.Type == "queryTestAuthor");
+    }
+
+    [Fact]
+    public async Task GetArticles_FilterOnIncludedResourceWithEmptyResult_ReturnsEmptyAsync()
+    {
+        // Filter on included resource that matches nothing
+        var response = await _client.GetAsync(
+            "/api/articles?filter[author.name]=NonexistentAuthor&include=author&page[number]=1&page[size]=10"
+        );
+
+        Assert.Equal(HttpStatusCode.OK, response.StatusCode);
+
+        var content = await response.Content.ReadAsStringAsync();
+        var document = JsonSerializer.Deserialize<JsonApiCollectionDocument<ResourceObject>>(
+            content,
+            _jsonOptions
+        );
+
+        Assert.NotNull(document?.Data);
+        Assert.Empty(document.Data);
+
+        // Pagination should reflect zero results
+        Assert.NotNull(document.Meta);
+        Assert.Equal(0, GetPaginationValue<int>(document.Meta, "totalResources"));
+    }
+
+    #endregion
+
     public void Dispose()
     {
         _client?.Dispose();

JsonApiToolkit.Tests/Mapping/InclusionMapperTests.cs

@@ -604,4 +604,134 @@ public void AddIncludedResources_ComplexScenario_HandlesCorrectly()
     }
 
     #endregion
+
+    #region Circular Reference Handling
+
+    [Fact]
+    public void AddIncludedResources_CircularReference_DoesNotCauseInfiniteLoop()
+    {
+        // Create circular reference: author -> books -> author
+        var author = new Author { Id = 1, Name = "John" };
+        var book = new Book
+        {
+            Id = 100,
+            Title = "Test Book",
+            Author = author,
+        };
+        author.Books.Add(book); // Circular: author.Books[0].Author == author
+
+        var included = new List<ResourceObject>();
+        var includePaths = new List<string> { "books", "books.author" };
+
+        // Should not throw or infinite loop
+        InclusionMapper.AddIncludedResources(author, includePaths, included);
+
+        // Should have book and author (author deduplicated - not added again via books.author)
+        Assert.Equal(2, included.Count);
+        Assert.Contains(included, r => r.Type == "book" && r.Id == "100");
+        Assert.Contains(included, r => r.Type == "author" && r.Id == "1");
+    }
+
+    [Fact]
+    public void AddIncludedResources_DeepCircularReference_HandlesCorrectly()
+    {
+        // Create deeper circular: author -> books -> chapters, books -> author
+        var author = new Author { Id = 1, Name = "John" };
+        var chapter = new Chapter { Id = 10, Title = "Chapter 1" };
+        var book = new Book
+        {
+            Id = 100,
+            Title = "Test Book",
+            Author = author,
+            Chapters = new List<Chapter> { chapter },
+        };
+        author.Books.Add(book);
+
+        var included = new List<ResourceObject>();
+        var includePaths = new List<string> { "books", "books.author", "books.chapters" };
+
+        InclusionMapper.AddIncludedResources(author, includePaths, included);
+
+        // Should have: book, author (via books.author - but deduplicated), chapter
+        Assert.Equal(3, included.Count);
+        Assert.Single(included, r => r.Type == "book");
+        Assert.Single(included, r => r.Type == "author");
+        Assert.Single(included, r => r.Type == "chapter");
+    }
+
+    [Fact]
+    public void AddIncludedResources_MutualCircularReference_HandlesCorrectly()
+    {
+        // Two books referencing the same author, author referencing both books
+        var author = new Author { Id = 1, Name = "John" };
+        var book1 = new Book
+        {
+            Id = 100,
+            Title = "Book 1",
+            Author = author,
+        };
+        var book2 = new Book
+        {
+            Id = 200,
+            Title = "Book 2",
+            Author = author,
+        };
+        author.Books.Add(book1);
+        author.Books.Add(book2);
+
+        var included = new List<ResourceObject>();
+        var includePaths = new List<string> { "author", "author.books" };
+
+        InclusionMapper.AddIncludedResources(
+            new List<Book> { book1, book2 },
+            includePaths,
+            included
+        );
+
+        // Author appears once (deduplicated), both books appear
+        Assert.Equal(3, included.Count);
+        Assert.Single(included, r => r.Type == "author");
+        Assert.Equal(2, included.Count(r => r.Type == "book"));
+    }
+
+    [Fact]
+    public void AddIncludedResources_SelfReferencingEntity_HandlesCorrectly()
+    {
+        // Simulate a self-referencing entity (e.g., parent-child)
+        var parent = new Author { Id = 1, Name = "Parent" };
+        var child = new Author { Id = 2, Name = "Child" };
+
+        // Simulate parent.Books containing "child" as if it were a hierarchical relationship
+        // Using the existing model, we'll test through the books relationship
+        var parentBook = new Book
+        {
+            Id = 100,
+            Title = "Parent's Book",
+            Author = parent,
+        };
+        var childBook = new Book
+        {
+            Id = 200,
+            Title = "Child's Book",
+            Author = child,
+        };
+        parent.Books.Add(parentBook);
+        child.Books.Add(childBook);
+
+        var included = new List<ResourceObject>();
+        var includePaths = new List<string> { "books", "books.author" };
+
+        InclusionMapper.AddIncludedResources(
+            new List<Author> { parent, child },
+            includePaths,
+            included
+        );
+
+        // 2 books + 2 authors (each author referenced via their own book.author)
+        Assert.Equal(4, included.Count);
+        Assert.Equal(2, included.Count(r => r.Type == "book"));
+        Assert.Equal(2, included.Count(r => r.Type == "author"));
+    }
+
+    #endregion
 }