# with-local-tmp-dir
Creates a temporary folder inside cwd, cds inside the folder, runs a function, and removes the folder. Especially useful for testing.
This package can be used to write file-based tests with real files. See below for some examples.
## Install
```bash
# npm
$ npm install with-local-tmp-dir
# Yarn
$ yarn add with-local-tmp-dir
```
## Basic Usage
```js
import withLocalTmpDir from 'with-local-tmp-dir';
import fs from 'fs-extra';
await withLocalTmpDir(() => {
console.log(process.cwd());
//> /Users/max/project/tmp-18815DudQxmdn03Rz
// Create some files
await fs.outputFile('foo.txt', 'foo bar');
await fs.outputFile('bar.txt', 'foo bar');
})
// Now the folder does not exist anymore
// The folder is removed even if an exception is thrown
await withLocalTmpDir(() => {
throw new Error('File could not be found')
});
```
## Reset
Instead of a function you can reset the state yourself instead of passing a function, i.e. change to the previous folder and remove the folder:
```js
import withLocalTmpDir from 'with-local-tmp-dir';
import fs from 'fs-extra';
// You can still pass options
const reset = await withLocalTmpDir();
console.log(process.cwd());
//> /Users/max/project/tmp-18815DudQxmdn03Rz
// Create some files
await fs.outputFile('foo.txt', 'foo bar');
await fs.outputFile('bar.txt', 'foo bar');
await reset();
// Now the folder does not exist anymore
```
## Options
You can pass an options object to the function:
* `mode`: The file mode to create with, it fallbacks to `0700`
* `prefix`: The optional prefix, fallbacks to `tmp-` if not provided
* `postfix`: The optional postfix
* `template`: [`mkstemp`](http://www.kernel.org/doc/man-pages/online/pages/man3/mkstemp.3.html) like filename template, no default
* `dir`: The base directory, falls back to cwd
* `tries`: How many times should the function try to get a unique filename before giving up, default `3`
* `keep`: Signals that the temporary file or directory should not be deleted on exit, default is `false`, means delete
* `unsafeCleanup`: Recursively removes the created temporary directory, even when it's not empty. default is `true`
```js
import withLocalTmpDir from 'with-local-tmp-dir';
import fs from 'fs-extra';
// do not cleanup if there are files
await withLocalTmpDir(() => {
await fs.outputFile('foo.txt', 'foo bar');
}, { unsafeCleanup: false });
// run in a subfolder
await withLocalTmpDir(() => {
console.log(process.cwd())
//> /Users/max/project/foo/tmp-18815DudQxmdn03Rz
}, { dir: 'foo' })
// use a different prefix
await withLocalTmpDir(() => {
console.log(process.cwd())
//> /Users/max/project/foo-18815DudQxmdn03Rz
}, { prefix: 'foo' })
```
## Unit Tests with output-files and endent
The most common use case for this package is probably unit tests with Mocha or Jest. The package itself is framework-agnostic, so you can use any of them. To make life easier when writing multiple files with multi-line text content, there are two handy packages: [output-files](git@github.com:dword-design/output-files.git) and [endent](https://github.com/indentjs/endent).
The following is an example for Mocha:
```js
const withLocalTmpDir = require('with-local-tmp-dir')
const outputFiles = require('output-files')
const endent = require('endent')
const funcToTest = require('.')
beforeEach(async function () {
this.resetWithLocalTmpDir = await withLocalTmpDir()
})
afterEach(async function () {
await this.resetWithLocalTmpDir()
})
it('works', async () => {
await outputFiles({
'foo.txt': endent`
Lorem ipsum
dolor sit
`,
'index.js': endent`
export default {
foo: 1,
bar: 2,
}
`,
})
funcToTest()
})
```
## Git-based tests
It is also possible to test libraries that make use of Git. You can instantiate a local Git repository inside the temporary folder and run Git operations on it:
```js
const withLocalTmpDir = require('with-local-tmp-dir')
const fs = require('fs-extra')
const execa = require('execa')
beforeEach(async function () {
this.resetWithLocalTmpDir = await withLocalTmpDir()
})
afterEach(async function () {
await this.resetWithLocalTmpDir()
})
it('works', async () => {
await execa.command('git init')
await execa.command('git config user.email "foo@bar.de"')
await execa.command('git config user.name "foo"')
await outputFile('foo.txt', 'foo bar')
await execa.command('git add .')
await execa.command('git commit -m "feat: init"')
funcToTest()
})
```
Be careful though, if the repository is not properly initialized, your user Git config might be overridden!
## Contribute
Are you missing something or want to contribute? Feel free to file an [issue](https://github.com/dword-design/with-local-tmp-dir/issues) or a [pull request](https://github.com/dword-design/with-local-tmp-dir/pulls)! ⚙️
## Support
Hey, I am Sebastian Landwehr, a freelance web developer, and I love developing web apps and open source packages. If you want to support me so that I can keep packages up to date and build more helpful tools, you can donate here:
If you want to send me a one time donation. The coffee is pretty good 😊.
Also for one time donations if you like PayPal.
Here you can support me regularly, which is great so I can steadily work on projects.
Thanks a lot for your support! ❤️
## See also
* [output-files](https://github.com/dword-design/output-files): Output a tree of files and directories by providing an object. Especially useful for testing with real files.
* [expect-mocha-image-snapshot](https://github.com/dword-design/expect-mocha-image-snapshot): A wrapper around jest-image-snapshot that makes it compatible to Mocha.
* [jest-image-matcher](https://github.com/dword-design/jest-image-matcher): A Jest matcher for image comparisons based on pixelmatch. Can also be used with Mocha. Useful for visual regression testing.
* [unify-mocha-output](https://github.com/dword-design/unify-mocha-output): Adjusts a Mocha output so that it is consistent across platforms and can be used for snapshot testing. Basically adjusts the checkmark symbol and removes time values.
* [mock-argv](https://github.com/dword-design/mock-argv): Temporarily overrides the command line arguments. This is useful for testing.
## License
[MIT License](https://opensource.org/license/mit/) © [Sebastian Landwehr](https://sebastianlandwehr.com)