Skip to content

Commit c549d04

Browse files
scordioscordio
committed
Add user guide
1 parent 8d98118 commit c549d04

8 files changed

Lines changed: 259 additions & 134 deletions

File tree

‎.github/workflows/main.yml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,3 +84,24 @@ jobs:
8484
cache: maven
8585
- name: Generate Javadoc
8686
run: ./mvnw $MAVEN_ARGS compile javadoc:javadoc
87+
88+
publish-user-guide:
89+
90+
name: Publish User Guide
91+
runs-on: ubuntu-latest
92+
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
93+
94+
steps:
95+
- uses: actions/checkout@v4
96+
- name: Set up Python
97+
uses: actions/setup-python@v5
98+
with:
99+
python-version: 3.x
100+
cache: 'pip'
101+
- name: Install Material for MkDocs
102+
run: pip install mkdocs-material
103+
- name: Publish to GitHub Pages
104+
run: |
105+
git config user.name '${{ github.actor }}'
106+
git config user.email '${{ github.actor }}@users.noreply.github.com'
107+
mkdocs gh-deploy

‎README.md‎

Lines changed: 10 additions & 134 deletions
Original file line numberDiff line numberDiff line change
@@ -1,141 +1,21 @@
1-
# Jimfs JUnit Jupiter [![Maven Central](https://img.shields.io/maven-central/v/io.github.scordio/jimfs-junit-jupiter?label=Maven%20Central)](https://mvnrepository.com/artifact/io.github.scordio/jimfs-junit-jupiter) [![javadoc](https://javadoc.io/badge2/io.github.scordio/jimfs-junit-jupiter/javadoc.svg)](https://javadoc.io/doc/io.github.scordio/jimfs-junit-jupiter)
1+
# Jimfs JUnit Jupiter [![Maven Central](https://img.shields.io/maven-central/v/io.github.scordio/jimfs-junit-jupiter?label=Maven%20Central)](https://central.sonatype.com/artifact/io.github.scordio/jimfs-junit-jupiter) [![javadoc](https://javadoc.io/badge2/io.github.scordio/jimfs-junit-jupiter/javadoc.svg)](https://javadoc.io/doc/io.github.scordio/jimfs-junit-jupiter)
22

33
[![CI](https://github.com/scordio/jimfs-junit-jupiter/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/scordio/jimfs-junit-jupiter/actions/workflows/main.yml?query=branch%3Amain)
44

5-
This project provides a [JUnit Jupiter][] extension for in-memory
6-
[`@TempDir`](https://junit.org/junit5/docs/current/api/org.junit.jupiter.api/org/junit/jupiter/api/io/TempDir.html)
7-
directories using the [Jimfs][] file system.
5+
This project provides a [JUnit Jupiter](https://junit.org/) extension for in-memory
6+
[`@TempDir`](https://docs.junit.org/current/api/org.junit.jupiter.api/org/junit/jupiter/api/io/TempDir.html) directories
7+
using the [Jimfs](https://github.com/google/jimfs) file system.
88

9-
## Getting Started
9+
## Documentation
1010

11-
### Compatibility
12-
13-
Jimfs JUnit Jupiter is based on JUnit Jupiter 5 and requires Java 8 or higher.
14-
15-
Compatibility is guaranteed only with the JUnit Jupiter versions from
16-
[5.10.0](https://junit.org/junit5/docs/5.10.0/release-notes/index.html)
17-
to the
18-
[latest](https://junit.org/junit5/docs/current/release-notes/index.html).
19-
20-
### Maven
21-
22-
```xml
23-
<dependency>
24-
<groupId>io.github.scordio</groupId>
25-
<artifactId>jimfs-junit-jupiter</artifactId>
26-
<version>${jimfs-junit-jupiter.version}</version>
27-
<scope>test</scope>
28-
</dependency>
29-
```
30-
31-
### Gradle
32-
33-
```kotlin
34-
testImplementation("io.github.scordio:jimfs-junit-jupiter:${jimfsJunitJupiterVersion}")
35-
```
36-
37-
## JimfsTempDirFactory
38-
39-
The simplest usage is to set the
40-
[`factory`](https://junit.org/junit5/docs/current/api/org.junit.jupiter.api/org/junit/jupiter/api/io/TempDir.html#factory())
41-
attribute of `@TempDir` to `JimfsTempDirFactory`:
42-
43-
```java
44-
@Test
45-
void test(@TempDir(factory = JimfsTempDirFactory.class) Path tempDir) {
46-
assertThat(tempDir.getFileSystem().provider().getScheme()).isEqualTo("jimfs");
47-
}
48-
```
49-
50-
`tempDir` is resolved to an in-memory temporary directory based on Jimfs, configured appropriately for the current
51-
platform.
52-
53-
## @JimfsTempDir
54-
55-
`@JimfsTempDir` is an annotation that can be used as a drop-in replacement for
56-
`@TempDir(factory = JimfsTempDirFactory.class)`:
57-
58-
```java
59-
@Test
60-
void test(@JimfsTempDir Path tempDir) {
61-
assertThat(tempDir.getFileSystem().provider().getScheme()).isEqualTo("jimfs");
62-
}
63-
```
64-
65-
The default behavior of the annotation is equivalent to using `JimfsTempDirFactory` directly: `tempDir` is resolved to
66-
an in-memory temporary directory based on Jimfs, configured appropriately for the current platform.
67-
68-
For better control over the underlying in-memory file system, `@JimfsTempDir` offers an optional `value` attribute
69-
that can be set to the desired configuration, one of:
70-
* `DEFAULT`: based on the corresponding [configuration parameter](#default-jimfs-configuration) (default)
71-
* `FOR_CURRENT_PLATFORM`: appropriate to the current platform
72-
* `OS_X`: for a Mac OS X-like file system
73-
* `UNIX`: for a UNIX-like file system
74-
* `WINDOWS`: for a Windows-like file system
75-
76-
For example, the following defines a Windows-like temporary directory, regardless of the platform on which the test is
77-
running:
78-
79-
```java
80-
@Test
81-
void test(@JimfsTempDir(WINDOWS) Path tempDir) {
82-
assertThat(tempDir.getFileSystem().getSeparator()).isEqualTo("\\");
83-
}
84-
```
85-
86-
## Configuration Parameters
87-
88-
Jimfs JUnit Jupiter supports JUnit
89-
[configuration parameters](https://junit.org/junit5/docs/current/user-guide/#running-tests-config-params).
90-
91-
### Default `@TempDir` Factory
92-
93-
The `junit.jupiter.tempdir.factory.default` configuration parameter sets the default factory to use, expecting a fully
94-
qualified class name.
95-
96-
For example, the following configures `JimfsTempDirFactory`:
97-
98-
```properties
99-
junit.jupiter.tempdir.factory.default=io.github.scordio.jimfs.junit.jupiter.JimfsTempDirFactory
100-
```
101-
102-
The factory will be used for all `@TempDir` annotations unless the annotation's `factory` attribute specifies a
103-
different type.
104-
105-
### Default Jimfs Configuration
106-
107-
The `jimfs.junit.jupiter.tempdir.configuration.default` configuration parameter sets the default Jimfs configuration to
108-
use. It expects one of the following values (case-insensitive):
109-
* `FOR_CURRENT_PLATFORM`: appropriate to the current platform (default)
110-
* `OS_X`: for a Mac OS X-like file system
111-
* `UNIX`: for a UNIX-like file system
112-
* `WINDOWS`: for a Windows-like file system
113-
114-
For example, the following defines a Windows-like temporary directory, regardless of the platform on which the test is
115-
running:
116-
117-
```properties
118-
jimfs.junit.jupiter.tempdir.configuration.default=windows
119-
```
120-
121-
All Jimfs-based temporary directories will be configured accordingly unless `@JimfsTempDir` is used with
122-
its `value` attribute set.
123-
124-
## Limitations
125-
126-
Jimfs JUnit Jupiter only supports annotated fields or parameters of type `Path`, since Jimfs is a non-default file
127-
system and `File` instances can only be associated with the default file system.
128-
129-
In addition, compared to the configuration options that Jimfs provides, Jimfs JUnit Jupiter offers a simplified
130-
interface to keep usage straightforward.
131-
132-
In case something is missing for your use case, please [raise an issue](../../issues/new)!
11+
- [User Guide](https://scordio.github.io/jimfs-junit-jupiter/)
12+
- [Release Notes](../../releases)
13313

13414
## Motivation
13515

13616
It is currently possible to use Jimfs and JUnit Jupiter together to create in-memory temporary directories for testing.
137-
However, this requires Jimfs in-memory file system handling to be integrated with JUnit Jupiter test lifecycle callbacks,
138-
boilerplate code that users must implement themselves.
17+
However, this requires Jimfs in-memory file system handling to be integrated with JUnit Jupiter test lifecycle
18+
callbacks, boilerplate code that users must implement themselves.
13919

14020
Starting from version 5.10, JUnit Jupiter offers a
14121
[`TempDirFactory` SPI](https://junit.org/junit5/docs/5.10.0/user-guide/#writing-tests-built-in-extensions-TempDirectory)
@@ -149,8 +29,4 @@ likely be discontinued if Google ever provides official support for this integra
14929

15030
## License
15131

152-
Jimfs JUnit Jupiter is released under version 2.0 of the [Apache License][].
153-
154-
[Apache License]: https://www.apache.org/licenses/LICENSE-2.0
155-
[Jimfs]: https://github.com/google/jimfs
156-
[JUnit Jupiter]: https://github.com/junit-team/junit-framework
32+
Jimfs JUnit Jupiter is released under version 2.0 of the [Apache License](https://www.apache.org/licenses/LICENSE-2.0).

‎docs/configuration-parameters.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Configuration Parameters
2+
3+
Jimfs JUnit Jupiter supports JUnit
4+
[configuration parameters](https://junit.org/junit5/docs/current/user-guide/#running-tests-config-params).
5+
6+
## Default `@TempDir` Factory
7+
8+
The `junit.jupiter.tempdir.factory.default` configuration parameter sets the default factory to use, expecting a fully
9+
qualified class name.
10+
11+
For example, the following configures `JimfsTempDirFactory`:
12+
13+
```properties
14+
junit.jupiter.tempdir.factory.default=io.github.scordio.jimfs.junit.jupiter.JimfsTempDirFactory
15+
```
16+
17+
The factory will be used for all `@TempDir` annotations unless the annotation's
18+
[`factory`](https://docs.junit.org/current/api/org.junit.jupiter.api/org/junit/jupiter/api/io/TempDir.html#factory())
19+
attribute specifies a different type.
20+
21+
## Default Jimfs Configuration
22+
23+
<!-- md:version 0.2.0 -->
24+
<!-- md:default `indigo` -->
25+
26+
The `jimfs.junit.jupiter.tempdir.configuration.default` configuration parameter sets the default Jimfs configuration to
27+
use. It expects one of the following values (case-insensitive):
28+
29+
* `FOR_CURRENT_PLATFORM`: appropriate to the current platform (default)
30+
* `OS_X`: for a Mac OS X-like file system
31+
* `UNIX`: for a UNIX-like file system
32+
* `WINDOWS`: for a Windows-like file system
33+
34+
For example, the following defines a Windows-like temporary directory, regardless of the platform on which the test is
35+
running:
36+
37+
```properties
38+
jimfs.junit.jupiter.tempdir.configuration.default=windows
39+
```
40+
41+
All Jimfs-based temporary directories will be configured accordingly unless `@JimfsTempDir` is used with its `value`
42+
attribute set.

‎docs/index.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Overview
2+
3+
Jimfs JUnit Jupiter is a [JUnit Jupiter](https://junit.org/) extension for in-memory
4+
[`@TempDir`](https://docs.junit.org/current/api/org.junit.jupiter.api/org/junit/jupiter/api/io/TempDir.html) directories
5+
using the [Jimfs](https://github.com/google/jimfs) file system.
6+
7+
## Compatibility
8+
9+
Jimfs JUnit Jupiter is based on JUnit Jupiter 5 and requires Java 8 or higher.
10+
11+
Compatibility is guaranteed only with the JUnit Jupiter versions from
12+
[5.10.0](https://junit.org/junit5/docs/5.10.0/release-notes/index.html)
13+
to the
14+
[latest](https://junit.org/junit5/docs/current/release-notes/index.html).
15+
16+
## Getting Started
17+
18+
[![Jimfs JUnit Jupiter](https://img.shields.io/maven-central/v/io.github.scordio/jimfs-junit-jupiter?label=Jimfs%20JUnit%20Jupiter)](https://central.sonatype.com/artifact/io.github.scordio/jimfs-junit-jupiter)
19+
20+
=== ":simple-apachemaven: Maven"
21+
22+
``` xml
23+
<dependency>
24+
<groupId>io.github.scordio</groupId>
25+
<artifactId>jimfs-junit-jupiter</artifactId>
26+
<version>${jimfs-junit-jupiter.version}</version>
27+
<scope>test</scope>
28+
</dependency>
29+
```
30+
31+
=== ":simple-gradle: Gradle"
32+
33+
``` kotlin
34+
testImplementation("io.github.scordio:jimfs-junit-jupiter:${jimfsJunitJupiterVersion}")
35+
```

‎docs/limitations.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Limitations
2+
3+
Jimfs JUnit Jupiter only supports annotated fields or parameters of type `Path`, since Jimfs is a non-default file
4+
system and `File` instances can only be associated with the default file system.
5+
6+
In addition, compared to the configuration options that Jimfs provides, Jimfs JUnit Jupiter offers a simplified
7+
interface to keep usage straightforward.
8+
9+
In case something is missing for your use case,
10+
please [:fontawesome-brands-github: raise an issue](https://github.com/scordio/jimfs-junit-jupiter/issues/new)!

‎docs/release-notes.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
template: redirect.html
3+
4+
location: https://github.com/scordio/jimfs-junit-jupiter/releases
5+
6+
title: Release Notes
7+
icon: fontawesome/brands/github
8+
---

‎docs/usage.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Usage
2+
3+
The simplest way to use Jimfs JUnit Jupiter is to set the
4+
[`factory`](https://junit.org/junit5/docs/current/api/org.junit.jupiter.api/org/junit/jupiter/api/io/TempDir.html#factory())
5+
attribute of `@TempDir` to `JimfsTempDirFactory`:
6+
7+
```java
8+
import io.github.scordio.jimfs.junit.jupiter.JimfsTempDirFactory;
9+
import org.junit.jupiter.api.Test;
10+
import org.junit.jupiter.api.io.TempDir;
11+
12+
@Test
13+
void test(@TempDir(factory = JimfsTempDirFactory.class) Path tempDir) {
14+
assertThat(tempDir.getFileSystem().provider().getScheme()).isEqualTo("jimfs");
15+
}
16+
```
17+
18+
`tempDir` is resolved to an in-memory temporary directory based on Jimfs, configured appropriately for the current
19+
platform.
20+
21+
While the example shows the injection of the temporary directory into a test method parameter,
22+
the same can also be done with class fields and constructor parameters.
23+
24+
## `@JimfsTempDir`
25+
26+
`@JimfsTempDir` is an annotation that can be used as a drop-in replacement for
27+
`@TempDir(factory = JimfsTempDirFactory.class)`:
28+
29+
```java
30+
import io.github.scordio.jimfs.junit.jupiter.JimfsTempDir;
31+
import org.junit.jupiter.api.Test;
32+
33+
@Test
34+
void test(@JimfsTempDir Path tempDir) {
35+
assertThat(tempDir.getFileSystem().provider().getScheme()).isEqualTo("jimfs");
36+
}
37+
```
38+
39+
The default behavior of the annotation is equivalent to using `JimfsTempDirFactory` directly: `tempDir` is resolved to
40+
an in-memory temporary directory based on Jimfs, configured appropriately for the current platform.
41+
42+
For better control over the underlying in-memory file system, `@JimfsTempDir` offers an optional `value` attribute
43+
that can be set to the desired configuration, one of:
44+
45+
* `DEFAULT`: based on the corresponding [configuration parameter](configuration-parameters.md#default-jimfs-configuration) (default)
46+
* `FOR_CURRENT_PLATFORM`: appropriate to the current platform
47+
* `OS_X`: for a Mac OS X-like file system
48+
* `UNIX`: for a UNIX-like file system
49+
* `WINDOWS`: for a Windows-like file system
50+
51+
For example, the following defines a Windows-like temporary directory, regardless of the platform on which the test is
52+
running:
53+
54+
```java
55+
import static io.github.scordio.jimfs.junit.jupiter.JimfsTempDir.Configuration.WINDOWS;
56+
57+
import io.github.scordio.jimfs.junit.jupiter.JimfsTempDir;
58+
import org.junit.jupiter.api.Test;
59+
60+
@Test
61+
void test(@JimfsTempDir(WINDOWS) Path tempDir) {
62+
assertThat(tempDir.getFileSystem().getSeparator()).isEqualTo("\\");
63+
}
64+
```

0 commit comments

Comments
 (0)