Skip to content

PT-4799: Test that chapter 1 goes below a new book's header lines - #53

Merged
katherinejensen00 merged 1 commit into
mainfrom
pt-4799-first-chapter-header-tests
Nov 13, 2026
Merged

katherinejensen00 merged 1 commit into
mainfrom
pt-4799-first-chapter-header-tests

Conversation

@katherinejensen00

@katherinejensen00 katherinejensen00 commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Test-only. Adds insertFirstChapter cases for a book that holds \h and \toc lines under its \id line, which is what a book Paratext creates looks like. They check that chapter 1 and its verses go below those lines and that the \id line stays the book's only one.

PT-4799 reported a second \id line and chapter 1 above the header lines after Simple mode's "Add chapter number". That was fixed by PT-4614 (#35, #37), but no test covered a book with header lines: the existing cases use only \id or \id + \mt1.

Why review this

Not part of the current epic. It locks in a reported bug's fix with tests so PT-4799 can be closed; small and test-only. The paranext-core half is paranext/paranext-core#3017.

Details

  • packages/platform/src/editor/markerEdit/chapterLineEditing.test.tsx: one new describe.each block, "below the header lines of a new book", in Standard, Formatted and paragraph-structure views (the last is what Simple mode uses; Formatted runs only under test:library-views, like its neighbours). Two header shapes: \h + \toc2 (the reported book), and \h + \toc1–\toc3 + \mt1. The \id text holds /, ", §$%& and umlauts, as a project name can.

AI Involvement

AI-assisted with Claude Code (Claude Opus 5.5). The commit carries a Co-Authored-By trailer.

Testing

  • chapterLineEditing.test.tsx: 119 passed.
  • Mutation-checked: inserting chapter 1 straight after the \id line turns all four new cases red.
  • Prettier and ESLint on the changed file.

Risk Level

None to the product: test-only.

🤖 Generated with Claude Code


This change is Reviewable

A book Paratext creates holds `\h` and `\toc` lines under its `\id`
line. Adds `insertFirstChapter` cases for that shape, with an `\id` text
full of special characters, in Standard view and the paragraph-structure
view that Simple mode's "Add chapter number" button uses: chapter 1 and
its verses go below the header lines, and the `\id` line stays the
book's only one. Test-only; the behavior came with PT-4614 (#35, #37).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@jolierabideau jolierabideau left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review: PT-4799 test coverage (paranext-core #3017 + scripture-editors #53)

Reviewed together, since these two test-only PRs split one job: the editor unit tests in #53 and the end-to-end Simple-mode spec in #3017. Nothing blocking. Both look good to merge once the points below are settled.

How the pair covers PT-4799's Definition of Done

DoD item Covered by Notes
1. Exactly one \id line, text unchanged, including special characters (!/"§$%&/()=?_öäüß) #53 (USJ, all three views) ⚠️ Special characters are checked only in the editor's USJ. The e2e \id text is empty book, so nothing checks them through the save path. See (1).
2. \c 1 and its verses go after the \id line and all front matter (\h, \toc1–\toc3, \mt…) #53 (both header shapes), #3017 (\h + \toc2) ✅ Good split: the full front-matter shape in unit tests, the reported shape end to end.
3. After saving and reopening, USFM reads \id, then the front matter in order, then \c 1, \v 1… #3017 ✅ The exact match against the saved USFM from the data provider covers this well. It doesn't reopen the editor, but the saved USFM is the part that matters.
4. An e2e test covers a book with front matter #3017 ✅ Covered, but isolated e2e doesn't run in CI, so this has only passed locally on Windows. See (3).

The fix itself shipped in PT-4614 (core #2948, editors #35/#37). The verification comment on the ticket (checked on main for both the \id-only book and the header-lines book) makes closing PT-4799 after these merge easy to justify.

Findings

(1) Consider: put the special-character \id text through the e2e save path (DoD item 1). #53 shows the editor keeps a project name like A_project_name_!/"§$%&/()=?_öäüß intact in USJ. The DoD singles out those characters, though, and the related ticket (PT-4090) is about / specifically, so the risk is just as much in USJ→USFM→disk as in the editor. prepareEmptySampleBook could take an optional \id text (default EMPTY_BOOK_ID_TEXT, since the Power spec finds the book by that text with getByText), and the Simple spec could pass the special-character name. The existing exact-match assertion would then check it with no other changes. If you'd rather leave it, a sentence on why the USJ-level check is enough would settle it.

(2) Discussion: the ticket's exact repro is no longer an e2e case. PT-4799 was reported on an \id-only book in Simple mode with the "Add chapter number" button. After #3017, the Simple spec uses the header-lines book, and the \id-only book is covered end to end only by the Power spec (through the \ palette, a different entry point), plus unit tests for the button's call (platform-scripture-editor.utils.test.ts "routes chapter 1 to insertFirstChapter…") and the editor's insert (chapterLineEditing.test.tsx "is inserted with empty verses by insertFirstChapter"). I confirmed both of those tests exist. I agree with the trade-off given one-test-per-spec and the cost of an Electron launch, and the header-lines book is the stronger case. I'm noting it so the decision is on record.

(3) DoD item 4 has only been verified on one machine. The isolated suite isn't in CI, and the spec has passed only on Windows. I can run it on macOS before merge if that helps.

(4) Nit (#53, consistency with the file): the two neighbouring insertFirstChapter blocks each go through a local insertWithVerses(content) helper, while the new block inlines the mount → act → getUsj steps. It's justified here because the new test also asserts inserted === true, which the helper doesn't return. Fine as is, just noting why it differs.

(5) CI: the Build on ubuntu-22.04 failure on #3017 is the snap store (cannot install "snapcraft": cannot get nonce from store) and has nothing to do with this change. A re-run should clear it. #53 is green.

Code patterns: what's done well

  • One exact-match assertion on the saved USFM (emptyBookUsfm + CHAPTER_1_SCAFFOLD_USFM) covers one \id line, header unchanged, and chapter below it in a single check, with no fragile partial matches.
  • The fixture API is hard to misuse: headerLines: string[] with the helper adding \r\n itself means a caller can't leave out a line ending, the optional default leaves the Power spec untouched, and the read-back makes a bad setup fail at setup rather than as a later timeout.
  • HEADER_LINES is built from JONAH_1.book, so the header can't drift from the \id line.
  • #53 runs in all three views, including paragraph-structure (the view Simple mode uses), and follows the file's describe.each(enabledViews(...)) / it.each conventions, so Formatted correctly runs only under test:library-views.
  • Mutation-checked: moving chapter 1 to right after the \id line turns all four new cases red, so the tests can fail.
  • Comments are forward-facing (behavior and rationale, no ticket narration), per forward-facing-comments.md. The ticket IDs are in the commit messages only.
  • The Simple spec's doc comment says plainly where the \id-only book is still covered.

🤖 Review assisted by Claude Code (Claude Opus 5.5)

@katherinejensen00

Copy link
Copy Markdown
Contributor Author

Thanks! (4): agreed, keeping it. It matches the file's other insertFirstChapter tests that check the return value ("is inserted with empty verses by insertFirstChapter", "is still inserted by insertFirstChapter"). (1), (3) and (5) are handled on paranext/paranext-core#3017.

@katherinejensen00
katherinejensen00 merged commit 11fdbf0 into main Nov 13, 2026
5 checks passed
@katherinejensen00
katherinejensen00 deleted the pt-4799-first-chapter-header-tests branch November 13, 2026 20:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants