Move to the paged document support in Verify 33.3: hidden sheets are read, and a sheet is a page

readme.md

@@ -10,6 +10,16 @@ Extends [Verify](https://github.com/VerifyTests/Verify) to allow verification of
 
 Converts Excel documents (xls, xlsb and xlsx) to csv for verification.
 
+Verifying a workbook produces:
+
+ * The workbook itself, as `.verified.xlsx`, `.verified.xlsb` or `.verified.xls`. An xlsx or an xlsb is a zip package, so it is passed through [DeterministicIoPackaging](https://github.com/SimonCropp/DeterministicIoPackaging), which removes the timestamps and the entry order that differ from one save to the next. This can be omitted with [`ExcludeTargets`](#choosing-what-is-verified).
+ * An info file, `.verified.txt`, with the names of its sheets.
+ * A csv of each sheet, named after the sheet: `#Sheet1.verified.csv`, `#Sheet2.verified.csv`, etc. A hidden sheet has a csv as any other, and is named under `HiddenSheets` in the info file. Options passed with `ExcelDataReaderOptions` are used as they are, so with those a hidden sheet is read only when `ReadHiddenWorksheets` is set. A reader that is passed in directly reads what it was created to read, and does not say which sheets are hidden. A sheet is a page, numbered by where it is among all the sheets of the workbook with hidden sheets counted, so `PagesToInclude` leaves out the csv of a sheet. A hidden sheet is counted whether or not the reader is asked to read it.
+
+An `ExcelDataReader` passed to a verification has no workbook to hand, so only the info file and the csv files are produced for it.
+
+The names of the csv files, and the setting that [leaves them out](#choosing-what-is-verified), are Verify's: the same for every plugin that splits a document into [derived targets](https://github.com/VerifyTests/Verify/blob/main/docs/converter.md#source-and-derived-targets).
+
 **See [Milestones](../../milestones?state=closed) for release notes.**
 
 
@@ -76,7 +86,7 @@ public Task VerifyExcelStream()
     return Verify(stream, "xlsx");
 }
 ```
-<sup><a href='/src/Tests/Samples.cs#L31-L40' title='Snippet source file'>snippet source</a> | <a href='#snippet-VerifyExcelStream' title='Start of snippet'>anchor</a></sup>
+<sup><a href='/src/Tests/Samples.cs#L122-L131' title='Snippet source file'>snippet source</a> | <a href='#snippet-VerifyExcelStream' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 
@@ -93,14 +103,30 @@ public Task VerifyExcelDataReader()
     return Verify(reader);
 }
 ```
-<sup><a href='/src/Tests/Samples.cs#L19-L29' title='Snippet source file'>snippet source</a> | <a href='#snippet-ExcelDataReader' title='Start of snippet'>anchor</a></sup>
+<sup><a href='/src/Tests/Samples.cs#L97-L107' title='Snippet source file'>snippet source</a> | <a href='#snippet-ExcelDataReader' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 
 ### Example snapshot
 
-<!-- snippet: Samples.VerifyExcel.verified.csv -->
-<a id='snippet-Samples.VerifyExcel.verified.csv'></a>
+The test `Samples.VerifyExcel` verifies a workbook with one sheet, named `Sheet1`. The names of its sheets are in `Samples.VerifyExcel.verified.txt`:
+
+<!-- snippet: Samples.VerifyExcel.verified.txt -->
+<a id='snippet-Samples.VerifyExcel.verified.txt'></a>
+```txt
+{
+  SheetNames: [
+    Sheet1
+  ]
+}
+```
+<sup><a href='/src/Tests/Samples.VerifyExcel.verified.txt#L1-L5' title='Snippet source file'>snippet source</a> | <a href='#snippet-Samples.VerifyExcel.verified.txt' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->
+
+And the sheet is in `Samples.VerifyExcel#Sheet1.verified.csv`:
+
+<!-- snippet: Samples.VerifyExcel#Sheet1.verified.csv -->
+<a id='snippet-Samples.VerifyExcel#Sheet1.verified.csv'></a>
 ```csv
 0,First Name,Last Name,Gender,Country,Date,Age,Id,Formula
 1,Dulce,Abril,Female,United States,2017-10-15,32,1562,1594
@@ -110,9 +136,11 @@ public Task VerifyExcelDataReader()
 5,Nereida,Magwood,Female,United States,2016-08-16,58,2468,2526
 6,Gaston,Brumm,Male,United States,2015-05-21,24,2554,2578
 ```
-<sup><a href='/src/Tests/Samples.VerifyExcel.verified.csv#L1-L7' title='Snippet source file'>snippet source</a> | <a href='#snippet-Samples.VerifyExcel.verified.csv' title='Start of snippet'>anchor</a></sup>
+<sup><a href='/src/Tests/Samples.VerifyExcel%23Sheet1.verified.csv#L1-L7' title='Snippet source file'>snippet source</a> | <a href='#snippet-Samples.VerifyExcel#Sheet1.verified.csv' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
-
+
+The csv is named after its sheet even when the workbook has no other, so that a second sheet adds a file rather than renaming the first.
+
 
 ### CsvDataWriterOptions
 
@@ -135,5 +163,53 @@ public Task CsvDataWriterOptions()
         .CsvDataWriterOptions(options);
 }
 ```
-<sup><a href='/src/Tests/Samples.cs#L42-L58' title='Snippet source file'>snippet source</a> | <a href='#snippet-CsvDataWriterOptions' title='Start of snippet'>anchor</a></sup>
+<sup><a href='/src/Tests/Samples.cs#L142-L158' title='Snippet source file'>snippet source</a> | <a href='#snippet-CsvDataWriterOptions' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
+
+
+### Choosing what is verified
+
+The csv files are what was derived from the workbook, so Verify's [`ExcludeDerivedTargets`](https://github.com/VerifyTests/Verify/blob/main/docs/paged-documents.md#leaving-out-what-was-derived) leaves them out, and only the sheet names are verified. The sheets are then not read:
+
+<!-- snippet: SheetNamesOnly -->
+<a id='snippet-SheetNamesOnly'></a>
+```cs
+[Test]
+public Task SheetNamesOnly() =>
+    VerifyFile("sample.xlsx")
+        .ExcludeDerivedTargets("csv");
+```
+<sup><a href='/src/Tests/Samples.cs#L133-L140' title='Snippet source file'>snippet source</a> | <a href='#snippet-SheetNamesOnly' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->
+
+`VerifierSettings.ExcludeDerivedTargets("csv")` does the same for every test.
+
+`ExcludeTargets("xlsx")` leaves out the workbook instead, keeping the info file and the csv files. It is then not built.
+
+A workbook has no pages, so the other settings for [paged documents](https://github.com/VerifyTests/Verify/blob/main/docs/paged-documents.md), `PageText` and `PagesToInclude`, have no effect on it.
+
+
+## Reviewing changes
+
+A change to a workbook is a change to several files: the workbook, the csv of each sheet that differs, and the info file when a sheet is added, removed or renamed. Verify tells the diff tool that the csv files and the info file were derived from the workbook, and [DiffEngineViewer](https://github.com/VerifyTests/DiffEngine/blob/main/docs/viewer.md#files-derived-from-a-document), which draws a workbook itself, shows them as one row and accepts them together. Other diff tools are given each file, as before.
+
+
+## Migrating from 1.x
+
+Version 2 moves to the [source and derived targets](https://github.com/VerifyTests/Verify/blob/main/docs/converter.md#source-and-derived-targets) of Verify 33.3. The API of this plugin is unchanged. What differs is that the workbook is now a snapshot too, and the name of a csv file, which Verify now decides, as it does for [every plugin that has moved](https://github.com/VerifyTests/Verify/blob/main/docs/paged-documents.md#migrating-from-33):
+
+| | 1.x | 2.x |
+| --- | --- | --- |
+| The workbook | Not a snapshot | `Tests.Report.verified.xlsx` |
+| A workbook with one sheet | `Tests.Report.verified.csv` | `Tests.Report#Sheet1.verified.csv` |
+| A workbook with several sheets | `Tests.Report#Sheet1.verified.csv` | Unchanged |
+| The info file | `Tests.Report.verified.txt` | Unchanged |
+
+`VerifierSettings.ExcludeTargets("xlsx")` keeps the workbook out of the snapshots, as it was in 1.x.
+
+A renamed snapshot shows as a new file and a pending delete. Accepting both, or running once with [AutoVerify](https://github.com/VerifyTests/Verify/blob/main/docs/autoverify.md), moves a test over. The content of the csv is unchanged, so source control shows it as a rename.
+
+Two cases that are less common also differ:
+
+ * A workbook that is itself a named target has its csv files named relative to it: one named `Attachment1` has `#Attachment1.Sheet1.verified.csv`, where 1.x did not use the name of the workbook. Passed to a verification as a `Target`, its info file takes the name as well: `#Attachment1.verified.txt`.
+ * An `ExcelDataReader` that has been moved past its last sheet has no csv. In 1.x it had one, holding only a header row.

src/Directory.Build.props

@@ -2,7 +2,7 @@
 <Project>
   <PropertyGroup>
     <NoWarn>CS1591;CS0649;CA1416;NU1608;NU1109</NoWarn>
-    <Version>1.0.0</Version>
+    <Version>2.0.0</Version>
     <LangVersion>preview</LangVersion>
     <AssemblyVersion>1.0.0</AssemblyVersion>
     <PackageTags>Sylvan.Data.Excel, Verify</PackageTags>

src/Directory.Packages.props

@@ -4,6 +4,7 @@
     <CentralPackageTransitivePinningEnabled>true</CentralPackageTransitivePinningEnabled>
   </PropertyGroup>
   <ItemGroup>
+    <PackageVersion Include="DeterministicIoPackaging" Version="1.0.0" />
     <PackageVersion Include="MarkdownSnippets.MsBuild" Version="28.5.0" />
     <PackageVersion Include="Polyfill" Version="11.4.1" />
     <PackageVersion Include="ProjectDefaults" Version="1.0.182" />
@@ -12,10 +13,10 @@
     <PackageVersion Include="Sylvan.Data.Csv" Version="1.4.4" />
     <PackageVersion Include="Sylvan.Data.Excel" Version="0.5.8" />
     <PackageVersion Include="TUnit" Version="1.72.16" />
-    <PackageVersion Include="Verify" Version="33.2.0" />
-    <PackageVersion Include="Verify.TUnit" Version="33.2.0" />
+    <PackageVersion Include="Verify" Version="33.3.0" />
+    <PackageVersion Include="Verify.TUnit" Version="33.3.0" />
     <PackageVersion Include="Argon" Version="0.37.0" />
-    <PackageVersion Include="DiffEngine" Version="20.6.0" />
+    <PackageVersion Include="DiffEngine" Version="20.7.0" />
     <PackageVersion Include="EmptyFiles" Version="8.20.0" />
     <PackageVersion Include="SimpleInfoName" Version="3.2.0" />
   </ItemGroup>

src/Tests/Samples.HiddenSheet#Sheet2.verified.csv

@@ -0,0 +1 @@
+aaa

src/Tests/Samples.HiddenSheet.verified.txt

@@ -0,0 +1,9 @@
+{
+  SheetNames: [
+    Sheet1,
+    Sheet2
+  ],
+  HiddenSheets: [
+    Sheet1
+  ]
+}

src/Tests/Samples.HiddenSheetIsCountedByPagesToInclude.verified.txt

@@ -0,0 +1,9 @@
+{
+  SheetNames: [
+    Sheet1,
+    Sheet2
+  ],
+  HiddenSheets: [
+    Sheet1
+  ]
+}

src/Tests/Samples.HiddenSheetIsCountedWhenNotRead#Sheet2.verified.csv

@@ -0,0 +1 @@
+aaa

src/Tests/Samples.HiddenSheetIsCountedWhenNotRead.verified.txt

@@ -0,0 +1,8 @@
+{
+  SheetNames: [
+    Sheet2
+  ],
+  HiddenSheets: [
+    Sheet1
+  ]
+}

src/Tests/Samples.HiddenSheetWithOptions#Sheet2.verified.csv

@@ -0,0 +1 @@
+aaa

src/Tests/Samples.HiddenSheetWithOptions.verified.txt

@@ -0,0 +1,8 @@
+{
+  SheetNames: [
+    Sheet2
+  ],
+  HiddenSheets: [
+    Sheet1
+  ]
+}

src/Tests/Samples.NamedWorkbook#Attachment1.Sheet2.verified.csv

@@ -0,0 +1 @@
+aaa

src/Tests/Samples.NamedWorkbook#Attachment1.verified.txt

@@ -0,0 +1,6 @@
+{
+  SheetNames: [
+    Sheet1,
+    Sheet2
+  ]
+}

src/Tests/Samples.PagesToInclude#Sheet2.verified.csv

@@ -0,0 +1 @@
+aaa

src/Tests/Samples.PagesToInclude.verified.txt

@@ -0,0 +1,6 @@
+{
+  SheetNames: [
+    Sheet1,
+    Sheet2
+  ]
+}

src/Tests/Samples.ReaderPastLastSheet.verified.txt

@@ -0,0 +1,5 @@
+{
+  SheetNames: [
+    Sheet1
+  ]
+}

src/Tests/Samples.SheetNamesOnly.verified.txt

@@ -0,0 +1,5 @@
+{
+  SheetNames: [
+    Sheet1
+  ]
+}

src/Tests/Samples.VerifyExcel#Sheet1.verified.csv

@@ -0,0 +1,7 @@
+0,First Name,Last Name,Gender,Country,Date,Age,Id,Formula
+1,Dulce,Abril,Female,United States,2017-10-15,32,1562,1594
+2,Mara,Hashimoto,Female,Great Britain,2016-08-16,25,1582,1607
+3,Philip,Gent,Male,France,2015-05-21,36,2587,2623
+4,Kathleen,Hanner,Female,United States,2017-10-15,25,3549,3574
+5,Nereida,Magwood,Female,United States,2016-08-16,58,2468,2526
+6,Gaston,Brumm,Male,United States,2015-05-21,24,2554,2578

src/Tests/Samples.VerifyExcelDataReader#Sheet1.verified.csv

@@ -0,0 +1,7 @@
+0,First Name,Last Name,Gender,Country,Date,Age,Id,Formula
+1,Dulce,Abril,Female,United States,2017-10-15,32,1562,1594
+2,Mara,Hashimoto,Female,Great Britain,2016-08-16,25,1582,1607
+3,Philip,Gent,Male,France,2015-05-21,36,2587,2623
+4,Kathleen,Hanner,Female,United States,2017-10-15,25,3549,3574
+5,Nereida,Magwood,Female,United States,2016-08-16,58,2468,2526
+6,Gaston,Brumm,Male,United States,2015-05-21,24,2554,2578

src/Tests/Samples.VerifyExcelStream#Sheet1.verified.csv

@@ -0,0 +1,7 @@
+0,First Name,Last Name,Gender,Country,Date,Age,Id,Formula
+1,Dulce,Abril,Female,United States,2017-10-15,32,1562,1594
+2,Mara,Hashimoto,Female,Great Britain,2016-08-16,25,1582,1607
+3,Philip,Gent,Male,France,2015-05-21,36,2587,2623
+4,Kathleen,Hanner,Female,United States,2017-10-15,25,3549,3574
+5,Nereida,Magwood,Female,United States,2016-08-16,58,2468,2526
+6,Gaston,Brumm,Male,United States,2015-05-21,24,2554,2578

src/Tests/Samples.VeryHiddenSheet#Sheet1.verified.csv

@@ -0,0 +1,7 @@
+0,First Name,Last Name,Gender,Country,Date,Age,Id,Formula
+1,Dulce,Abril,Female,United States,2017-10-15,32,1562,1594
+2,Mara,Hashimoto,Female,Great Britain,2016-08-16,25,1582,1607
+3,Philip,Gent,Male,France,2015-05-21,36,2587,2623
+4,Kathleen,Hanner,Female,United States,2017-10-15,25,3549,3574
+5,Nereida,Magwood,Female,United States,2016-08-16,58,2468,2526
+6,Gaston,Brumm,Male,United States,2015-05-21,24,2554,2578

src/Tests/Samples.VeryHiddenSheet#Sheet2.verified.csv

@@ -0,0 +1 @@
+aaa

src/Tests/Samples.VeryHiddenSheet.verified.txt

@@ -0,0 +1,9 @@
+{
+  SheetNames: [
+    Sheet1,
+    Sheet2
+  ],
+  HiddenSheets: [
+    Sheet1
+  ]
+}