Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@ on:
push:
branches: [main]
pull_request:
# Run on a branch without opening a pull request.
workflow_dispatch:

permissions:
contents: read
Expand Down
52 changes: 49 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,52 @@ Optional hooks:

Inside a case, `LocalVCaseVariant.current` gives the axes and the fixture name.

### Per-case capture settings

A case can change how it is captured. Every setting is optional, defaults to the host's
behaviour, and is written to the manifest's `capture` object only when set, so existing
cases, manifests and goldens are unchanged.

| `@VCase` parameter | default | effect |
|---|---|---|
| `maxWidth` | `0` (host's bound, by default the viewport width) | width bound in dp of a component capture, for content wider than the host allows (a wide gallery) |
| `maxHeight` | `0` (host's bound, by default 4x the viewport height) | height bound in dp of a component capture |
| `settleFrames` | `-1` (host's `settleFrames`) | frames rendered before the captured one, e.g. `2` for a popup that lays itself out a frame late |
| `frameIntervalMs` | `-1` (host's `frameTimeNanos`) | frame `i` renders at `i * frameIntervalMs` ms; `0` renders every frame at time 0 |

```kotlin
@VCase("ds.choice-list.gallery", maxWidth = 1600) // wider than the 1200dp gallery bound
@VCase("ds.tooltip.open", settleFrames = 2, frameIntervalMs = 0) // popup settled, animations not started
@VCase("ds.toast.shown", settleFrames = 20, frameIntervalMs = 16) // a 300 ms fade-in has finished
```

- `maxWidth` / `maxHeight` replace the bounds of the host's `CaptureSize.WrapContent`. A
screen is captured at its viewport, so the manifest check rejects them on screens.
- `settleFrames` applies to the capture pass. The measure pass of a component (which finds
its content size) keeps the host's count.
- `settleFrames = N, frameIntervalMs = 0` matches a hand-written
`repeat(N) { scene.render() }; scene.render()` on an `ImageComposeScene`: state, effects
and popups settle, while time-driven animations stay at their start. Give a positive
interval to let animations run.

### Wide layouts and the mouse

The pointer axis (`touch`, `fine`) is how a case asks for mouse sizing:
`pointer = ["fine"]`, or `["touch", "fine"]` for both. A wide layout (a desktop type scale,
larger panes) is a viewport with a size class:

```kotlin
ManifestViewport("wide", 1200, 2400, 2f, optIn = true, sizeClass = VCaseSizeClass.WIDE)

@VCase("ds.desktop-scale.gallery", viewport = ["wide"], pointer = ["fine", "touch"])
```

The host reads `variant.axes.viewport.sizeClass` and `variant.axes.pointer` in `Wrap` and
pins the theme's layout and input modes with them. It should not derive them from the
capture size: a component is captured at its content size, which says nothing about the
window it was designed for. `sizeClass` is free text (`VCaseSizeClass.COMPACT` and `WIDE` are
the conventional names). It is not an axis of its own, so it never appears in file names.

### 3. Add one test class

```kotlin
Expand Down Expand Up @@ -164,10 +210,10 @@ export default function Variants() { return <ButtonGallery />; }

| module | what |
|---|---|
| `vcase-annotations` | `@VCase`, `@VCaseDivergence`, `VCaseKind`, axis model (`VCaseAxis`, `VCasePointer`, `VCaseViewport`, `VCaseAxisValues`). KMP, no dependencies. |
| `vcase-core` | JVM. Manifest model + JSON (`VCaseManifest`, `VCaseJson`), `ManifestValidation`, `VCaseIds`, `AxisExpansion` / `VCaseVariant`, `ManifestDiff`, `ImageCompare` / `PixelTolerance` / `RegionTolerance`, `CaptureMeta`, `GoldenStore` / `GoldenRun` / `RunSummary`, `HtmlReport`. |
| `vcase-annotations` | `@VCase`, `@VCaseDivergence`, `VCaseKind`, axis model (`VCaseAxis`, `VCasePointer`, `VCaseViewport`, `VCaseSizeClass`, `VCaseAxisValues`). KMP, no dependencies. |
| `vcase-core` | JVM. Manifest model + JSON (`VCaseManifest`, `ManifestCapture`, `VCaseJson`), `ManifestValidation`, `VCaseIds`, `AxisExpansion` / `VCaseVariant`, `ManifestDiff`, `ImageCompare` / `PixelTolerance` / `RegionTolerance`, `CaptureMeta`, `GoldenStore` / `GoldenRun` / `RunSummary`, `HtmlReport`. |
| `vcase-compose-desktop` | JVM, Compose Desktop. `VCaseScanner` (ComposablePreviewScanner `JvmAnnotationScanner` + ClassGraph), `VCaseHost`, `CaptureSize`, `LocalVCaseVariant`, `DesktopRenderer` (ImageComposeScene, renderer `desktop-skiko`), `runVCases`, `VCaseDesktopConfig`, `VCaseDesktopTest`. |
| `samples/compose-desktop` | Four cases, a host, the one test class, committed goldens. |
| `samples/compose-desktop` | Seven cases (including a wide capture, a settled popup and a wide size class with both pointers), a host, the one test class, committed goldens. |

## Building

Expand Down
9 changes: 8 additions & 1 deletion docs/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -113,6 +113,11 @@ Phase 1 additions to `vcase/1` (all optional, omitted from the JSON while unset)
- `cases[].formerly`: previous ids.
- `cases[].needsDevice`: the case can only be rendered on a device or emulator.
- `divergences[].expires`: an ISO date.
- `viewport[].sizeClass`: the layout mode the host pins for the viewport (`compact`, `wide`).
It is not an axis and is not part of file names.
- `cases[].capture`: per-case capture settings, each optional: `maxWidth` / `maxHeight`
(dp bounds of a component capture), `settleFrames` (frames before the captured one) and
`frameIntervalMs` (frame `i` at `i * frameIntervalMs` ms; 0 = every frame at time 0).

### Id rules **[built]**

Expand Down Expand Up @@ -165,7 +170,9 @@ fun ChannelMembersCase(data: MembersFixture) {
`ScreenshotTimeContext`) and pinned fonts. The project injects its own theme and these
freeze settings through a `VCaseHost` interface. The framework does not know about Raft.
**[built]** Frames render at fixed times (`frameTimeNanos`), and density and font
scale come from the axes.
scale come from the axes. A case can override the frame plan (`settleFrames`,
`frameIntervalMs`) and the content-size bounds (`maxWidth`, `maxHeight`); the host maps
the viewport's `sizeClass` and the pointer axis to the theme's layout and input modes.
- The data parameter's type follows from the fixture name. The adapter deserializes the
generated JSON into it (kotlinx.serialization). **[planned]** In phase 1 cases have no
parameters. A case with a parameter is reported as an error. The fixture name is
Expand Down
30 changes: 29 additions & 1 deletion docs/pilot-raft-mobile.md
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,35 @@ tasks, and the legacy golden directory.
harness does. Making `locale` a real axis changes the type styles, so it needs a re-record.
- **Tests with interaction** (hover, pointer density, pull-down, toast timing) need more
host hooks: settle frames per case, `LocalRaftSpinnerStillStep`, input injection. These
tests come last.
tests come last. Per-case settle frames, wide captures and the wide / mouse modes now
exist (see below); input injection does not.

## Capture settings the remaining galleries need

After batch 2, the remaining `RaftScreenshot` tests use three `capture` parameters that the
first host could not express. Each maps to a vcase setting:

| `RaftScreenshot.capture(...)` | `@VCase` | legacy tests |
|---|---|---|
| `maxWidthDp = 1340 / 1400 / 1600` | `maxWidth = 1340 / 1400 / 1600` | ThemeDecor (`top_actions`), ChoicePicker, ChoiceList, Combobox (`sheet`) |
| `settleFrames = N` | `settleFrames = N, frameIntervalMs = 0` | AppRail, DisplayComponent, FrameInsets, InteractiveComponent, MessageReaction, MobileNavServer, PointerDensity, PreviewCard, SideActionColumn, SidebarSectionMouse, ThemeDecor, ToastHost, TopBar |
| `scale = RaftScale.Wide` | `viewport = ["wide"]` | DesktopScale, FitToolbar (`members_fine`), PointerDensity |
| `pointerInput = RaftPointerInput.Fine` | `pointer = ["fine"]` (`["fine", "touch"]` for both) | DesktopScale, FitToolbar (`members_fine`), PointerDensity, SidebarSectionMouse |

Pixel parity notes:

- `RaftScreenshot` renders every frame with `scene.render()`, that is at time 0, and measures
the content with one frame. `settleFrames = N, frameIntervalMs = 0` does the same: the
capture pass renders N + 1 frames at time 0, and the measure pass keeps the host's count
(0 for `RaftVCaseHost`, one frame). Without `frameIntervalMs = 0` the frames would step
16 ms and animations would move.
- The host needs a `wide` viewport with the same bounds as `compact`:
`ManifestViewport("wide", 1200, 2400, 2f, optIn = true, sizeClass = VCaseSizeClass.WIDE)`,
and `Wrap` picks `RaftScale.Wide` from `variant.axes.viewport.sizeClass` (Compact
otherwise). Its golden names end in `,wide,fine` / `,wide,touch`.
- `maxWidth` replaces the host's `CaptureSize.WrapContent(1200, 2400)` width only; the
2400 dp height bound stays.

- **Source line numbers in the manifest.** Editing above a case changes its `source` line,
and the manifest check then asks for a `vcase.mode=scan`. This is by design (the manifest
must equal the scan), but it is a real cost in review noise.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
package dev.vcase.sample

import androidx.compose.foundation.background
import androidx.compose.foundation.border
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.foundation.text.BasicText
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.IntOffset
import androidx.compose.ui.unit.dp
import androidx.compose.ui.window.Popup
import dev.vcase.VCase

// Cases that change how they are captured, not only what they show.

/**
* Wider than the 360dp phone viewport, which bounds a component by default: `maxWidth` lets
* the capture grow to the content instead of cutting it at 360dp.
*/
@VCase("ds.toolbar.wide", maxWidth = 720)
@Composable
fun WideToolbarCase() {
Row(Modifier.width(600.dp), horizontalArrangement = Arrangement.SpaceBetween) {
listOf("Bold", "Italic", "Link", "Quote", "Code", "List").forEach { SampleButton(it, ButtonKind.Secondary) }
}
}

/**
* A tooltip open under its button. A popup lays itself out a frame after its anchor, so the
* capture waits two settle frames; at time 0 each, so a fade-in would not have started
* (`frameIntervalMs = 0`).
*/
@VCase("ds.tooltip.open", settleFrames = 2, frameIntervalMs = 0)
@Composable
fun TooltipOpenCase() {
Box(Modifier.width(180.dp).height(100.dp)) {
SampleButton("Save")
Popup(offset = IntOffset(0, 112)) {
val c = SampleTheme.colors
Box(
Modifier
.background(c.text, RoundedCornerShape(6.dp))
.border(1.dp, c.border, RoundedCornerShape(6.dp))
.padding(horizontal = 8.dp, vertical = 4.dp),
) {
BasicText("Save changes (Ctrl+S)", style = SampleTheme.body.copy(color = c.canvas))
}
}
}
}

/**
* The buttons on a desktop-width window: the `desktop` viewport's size class is `wide`, so
* the host pins the wide type scale; with a mouse (`fine`) the buttons are shorter than with
* a finger.
*/
@VCase("ds.button.desktop", viewport = ["desktop"], pointer = ["fine", "touch"])
@Composable
fun DesktopButtonsCase() {
Row(horizontalArrangement = Arrangement.spacedBy(8.dp)) {
SampleButton("Cancel", ButtonKind.Secondary)
SampleButton("Save")
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.text.platform.Font
import androidx.compose.ui.unit.sp

/** A tiny design system: two palettes, one font, a touch / fine pointer switch. */
/** A tiny design system: two palettes, one font, a touch / fine pointer switch, a compact / wide scale. */
@Immutable
data class SampleColors(
val canvas: Color,
Expand Down Expand Up @@ -50,8 +50,12 @@ val DarkColors =

enum class SamplePointer { Touch, Fine }

/** The layout mode an app picks from its window width: wide windows get a larger type scale. */
enum class SampleScale { Compact, Wide }

val LocalSampleColors = staticCompositionLocalOf { LightColors }
val LocalSamplePointer = staticCompositionLocalOf { SamplePointer.Touch }
val LocalSampleScale = staticCompositionLocalOf { SampleScale.Compact }

object SampleFonts {
private fun bytes(name: String): ByteArray =
Expand All @@ -72,20 +76,32 @@ object SampleFonts {
object SampleTheme {
val colors: SampleColors @Composable get() = LocalSampleColors.current
val pointer: SamplePointer @Composable get() = LocalSamplePointer.current
val scale: SampleScale @Composable get() = LocalSampleScale.current

val body: TextStyle @Composable get() = TextStyle(fontFamily = SampleFonts.family, fontSize = 14.sp, color = colors.text)
val title: TextStyle @Composable get() = TextStyle(fontFamily = SampleFonts.family, fontSize = 18.sp, fontWeight = FontWeight.Bold, color = colors.text)
val body: TextStyle
@Composable get() =
TextStyle(fontFamily = SampleFonts.family, fontSize = if (scale == SampleScale.Wide) 16.sp else 14.sp, color = colors.text)
val title: TextStyle
@Composable get() =
TextStyle(
fontFamily = SampleFonts.family,
fontSize = if (scale == SampleScale.Wide) 22.sp else 18.sp,
fontWeight = FontWeight.Bold,
color = colors.text,
)
}

@Composable
fun SampleTheme(
dark: Boolean,
pointer: SamplePointer = SamplePointer.Touch,
scale: SampleScale = SampleScale.Compact,
content: @Composable () -> Unit,
) {
CompositionLocalProvider(
LocalSampleColors provides if (dark) DarkColors else LightColors,
LocalSamplePointer provides pointer,
LocalSampleScale provides scale,
content = content,
)
}
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,9 @@ class RecordVerifyTest {
assertTrue(recorded.ok, recorded.describe())
val stems = recorded.summary!!.results.map { it.variant.fileStem }.toSet()
// 4 button (2 themes x 2 pointers) + 2 badge + 4 card (2 themes x 2 font scales) + 4 screen (2 x 2 viewports)
assertEquals(14, stems.size, stems.toString())
// + 2 wide toolbar + 2 tooltip + 4 desktop button (2 themes x 2 pointers)
assertEquals(22, stems.size, stems.toString())
assertTrue("ds.button.desktop@dark,desktop,fine" in stems)
assertTrue("ds.button.variants@dark,phone,fine" in stems)
assertTrue("ds.card.default@light,phone,fs1.3" in stems)
assertTrue("screen.inbox.empty@dark,wide" in stems)
Expand Down Expand Up @@ -73,4 +75,31 @@ class RecordVerifyTest {
val badge = ImageIO.read(File(dir, "ds.badge.counts@light,phone.png"))
assertTrue(badge.width < 400 && badge.height < 200, "${badge.width}x${badge.height}")
}

@Test
fun captureSettings() {
val root = kotlin.io.path.createTempDirectory("vcase-sample").toFile()
val r =
runVCases(
SampleVCaseHost,
VCaseDesktopConfig(
packages = listOf("dev.vcase.sample"),
mode = VCaseMode.Record,
goldensDir = File(root, "g"),
outputDir = File(root, "o"),
manifestFile = null,
filter = listOf("ds.toolbar.wide", "ds.button.desktop"),
),
)
assertTrue(r.ok, r.describe())
val dir = File(root, "g/desktop-skiko")
// maxWidth = 720: 600dp of toolbar + 2 x 16dp of canvas, past the 360dp phone bound.
val toolbar = ImageIO.read(File(dir, "ds.toolbar.wide@light,phone.png"))
assertEquals(1264, toolbar.width)
assertTrue(r.summary!!.results.all { it.meta!!.warnings.isEmpty() }, r.summary!!.results.map { it.meta!!.warnings }.toString())
// With a mouse the controls are shorter than with a finger.
val desktop = ImageIO.read(File(dir, "ds.button.desktop@light,desktop,fine.png"))
val desktopTouch = ImageIO.read(File(dir, "ds.button.desktop@light,desktop,touch.png"))
assertTrue(desktopTouch.height > desktop.height, "touch ${desktopTouch.height} vs fine ${desktop.height}")
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import dev.vcase.VCasePointer
import dev.vcase.VCaseSizeClass
import dev.vcase.compose.desktop.VCaseHost
import dev.vcase.core.ManifestCase
import dev.vcase.core.ManifestDefaults
Expand All @@ -22,8 +23,14 @@ object SampleVCaseHost : VCaseHost {
override val defaults =
ManifestDefaults(
theme = listOf("light", "dark"),
// `wide` is opt-in: only cases that list it (screens) are captured at it.
viewport = listOf(ManifestViewport("phone", 360, 640, 2f), ManifestViewport("wide", 960, 600, 1f, optIn = true)),
// `wide` and `desktop` are opt-in: only cases that list them are captured at them.
// `desktop` declares the wide size class, which the host maps to the wide type scale.
viewport =
listOf(
ManifestViewport("phone", 360, 640, 2f),
ManifestViewport("wide", 960, 600, 1f, optIn = true),
ManifestViewport("desktop", 1280, 800, 2f, optIn = true, sizeClass = VCaseSizeClass.WIDE),
),
locale = listOf("en"),
pointer = listOf("touch"),
)
Expand Down Expand Up @@ -52,7 +59,9 @@ object SampleVCaseHost : VCaseHost {
content: @Composable () -> Unit,
) {
val pointer = if (variant.axes.pointer == VCasePointer.Fine) SamplePointer.Fine else SamplePointer.Touch
SampleTheme(dark = variant.axes.theme == "dark", pointer = pointer) {
// The layout mode comes from the viewport's size class, never from the capture size.
val scale = if (variant.axes.viewport.sizeClass == VCaseSizeClass.WIDE) SampleScale.Wide else SampleScale.Compact
SampleTheme(dark = variant.axes.theme == "dark", pointer = pointer, scale = scale) {
if (variant.case.kind == ManifestCase.KIND_SCREEN) {
content()
} else {
Expand Down
Loading
Loading