Document mock adapter usage

[rafael81]

Summary

• add a Mock Adapter docs page under Get pREST
• link it from the Development Guide testing section
• add it to the GitBook summary navigation
• fix the Basic usage heading level after review feedback

Follow-up for prest/prest#963 after maintainer guidance to move docs into this repository. Related funded IssueHunt item: prest/prest#284.

Validation

git diff --check

Transparency note: this documentation PR is AI-assisted with OpenAI Codex. I used it to inspect the existing mock adapter behavior, draft the docs, and check the changed files; I reviewed the final content before submitting.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds comprehensive documentation for the mock adapter, a hand-written test utility that provides in-memory adapter behavior without real PostgreSQL connections. The new guide covers instantiation, response queueing, permission handling, and distinguishes it from the generated mockgen package, with cross-links from the development guide and table of contents.

Changes

Mock Adapter Documentation

Layer / File(s)	Summary
Mock Adapter Overview and Setup get-prest/mock-adapter.md	Introduces the mock adapter package and documents how to create it with mock.New(t), assign it to config.PrestConf.Adapter, and how the embedded database/sql driver registration enables transaction helper paths without network access.
Mock Adapter Operations, Permissions, and Patterns get-prest/mock-adapter.md	Describes queued-response consumption and test failure when operations exceed available items, details permission behavior via TablePermissions reading config.PrestConf.AccessConf, and explains the hand-written controller-style approach vs. the generated mockgen package for strict expectations.
Cross-Document References and Table of Contents get-prest/development-guide.md, SUMMARY.md	Adds guidance in the development guide directing tests that don't require PostgreSQL to use the mock adapter, and includes a TOC entry linking to the new documentation.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related issues

• Add documentation about mock adapter prest#284: Adds documentation for the mock adapter package, directly addressing the same feature and testing patterns covered in this PR.

Poem

🐰 A mock adapter hops into view,
In-memory tests now ring true!
No PostgreSQL in sight—
Just queued responses, clean and bright,
Permissions flow, and tests take flight! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Document mock adapter usage' directly and concisely summarizes the primary change: adding documentation for the mock adapter. It accurately reflects the main objective of the PR.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@get-prest/mock-adapter.md`:
- Line 10: The "Basic usage" heading is currently H3 (### Basic usage) which
skips H2 and breaks document structure; change that heading to H2 (## Basic
usage) so the document follows an H1 → H2 → ... hierarchy and restores proper
navigation, TOC generation, and accessibility for screen readers.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: de76dd5a-9b9e-4986-a674-6095f3e955d2

📥 Commits

Reviewing files that changed from the base of the PR and between ca4fcd6 and bdbe576.

📒 Files selected for processing (3)

• SUMMARY.md
• get-prest/development-guide.md
• get-prest/mock-adapter.md

[rafael81]

Transparency note: this documentation PR is AI-assisted with OpenAI Codex. I used it to inspect the existing mock adapter behavior, draft the docs, and check the changed files; I reviewed the final content before submitting. This is the docs-repo follow-up for the funded IssueHunt item tracked at prest/prest#284 and the original PR prest/prest#963.

[woahwhattheheck]

The permissions example needs to match the actual mock API: Mock.TablePermissions accepts five strings and reads the instance's AccessConf, rather than the global config. I checked the complete guide and pinned implementation at prest/prest b84da9b48fc5ae0765af67ab523314665f3d6741. This scoped correction preserves @rafael81's original documentation and maintainer-selected carrier. No Go compilation or docs build was run; AI-assisted review.

The corresponding merged source packet is https://github.com/woahwhattheheck/commons/tree/main/work/bounty-intake/prest284-docs3-permissions-20261005-7ca6 .

[woahwhattheheck]

Configure the mock instance and supply its two ignored leading arguments. This avoids both the three-argument compile error and a globally configured mock that remains unrestricted.

Suggested change

	`TablePermissions` reads `config.PrestConf.AccessConf`. When access
	restrictions are disabled, it returns `true`. When restrictions are enabled, it
	checks table-level permissions first and then user-specific table permissions
	when a user name is provided.
	This lets tests cover authorization behavior without a database fixture:
	```go
	config.PrestConf.AccessConf.Restrict = true
	config.PrestConf.AccessConf.Tables = []config.TablesConf{
	{Name: "books", Permissions: []string{"read"}},
	}
	if !adapter.TablePermissions("books", "read", "") {
	t.Fatal("expected read access")
	}
	```
	`TablePermissions` reads `adapter.AccessConf`. When access
	restrictions are disabled, it returns `true`. When restrictions are enabled, it
	checks table-level permissions first and then user-specific table permissions
	when a user name is provided.
	This lets tests cover authorization behavior without a database fixture:
	```go
	adapter.AccessConf.Restrict = true
	adapter.AccessConf.Tables = []config.TablesConf{
	{Name: "books", Permissions: []string{"read"}},
	}
	if !adapter.TablePermissions("", "", "books", "read", "") {
	t.Fatal("expected read access")
	}
	```
	This mock ignores its first two parameters, so empty strings are appropriate
	here. Permission settings belong to this mock instance; changing the global
	access configuration does not configure it.