File: README.md

package info (click to toggle)
ruby-fakefs 1.2.0-1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, sid
  • size: 496 kB
  • sloc: ruby: 6,810; makefile: 5
file content (223 lines) | stat: -rw-r--r-- 5,284 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
FakeFS [![build status](https://travis-ci.org/fakefs/fakefs.svg?branch=master)](https://travis-ci.org/fakefs/fakefs)
======

Mocking calls to FileUtils or File means tightly coupling tests with the implementation.

``` ruby
it "creates a directory" do
  FileUtils.expects(:mkdir).with("directory").once
  Library.add "directory"
end
```

The above test will break if `mkdir_p` is used instead.
Refactoring code should not necessitate refactoring tests.

A better approach is to use a temp directory if you are working with relative directories.

```Ruby
require 'tmpdir'

it "creates a directory" do
  Dir.mktmpdir do |dir|
    Dir.chdir dir do
      Library.add "directory"
      assert File.directory?("directory")
    end
  end
end
```

But if you are working with absolute directories or do not want to use temporary directories, use FakeFS instead:

``` ruby
it "creates a directory" do
  FakeFS do
    Library.add "directory"
    assert File.directory?("directory")
  end
end
```

Installation
------------

```Bash
gem install fakefs
```

Usage
-----

To fake out the FS:

``` ruby
require 'fakefs'
```

Temporarily faking the FS
-------------------------

``` ruby
require 'fakefs/safe'

FakeFS.activate!
# your code
FakeFS.deactivate!

# or
FakeFS do
  # your code
end
```

Rails
-----

In rails projects, add this to your Gemfile:

``` ruby
gem "fakefs", require: "fakefs/safe"
```

RSpec
-----


Include FakeFS::SpecHelpers to turn FakeFS on and off in an example group:

``` ruby
require 'fakefs/spec_helpers'

describe "my spec" do
  include FakeFS::SpecHelpers
end
```

See `lib/fakefs/spec_helpers.rb` for more info.

To use FakeFS within a single test and be guaranteed a fresh fake filesystem:
``` ruby
require 'fakefs/safe'

describe "my spec" do
  context "my context" do
    it "does something to the filesystem"
      FakeFS.with_fresh do
        # whatever it does
      end
    end
  end
end
```


FakeFs --- `TypeError: superclass mismatch for class File`
--------------

`pp` and `fakefs` may collide, even if you're not actually explicitly using `pp`.  Adding `require 'pp'` before `require 'fakefs'` should fix the problem locally.  For a module-level fix, try adding it to the `Gemfile`:

```ruby
source "https://rubygems.org"

require 'pp'
# list of gems
```

The problem may not be limited to `pp`; any gems that add to `File` may be affected.

Working with existing files
---------------------------

Clone existing directories or files to reuse them during tests, they are safe to modify.

```ruby
FakeFS do
  config = File.expand_path('../../config', __FILE__)

  FakeFS::FileSystem.clone(config)
  expect(File.read("#{config}/foo.yml")).to include("original-content-of-foo")

  File.write("#{config}/foo.yml"), "NEW")
  expect(File.read("#{config}/foo.yml")).to eq "NEW"
end
```

Integrating with other filesystem libraries
--------------------------------------------
Third-party libraries may add methods to filesystem-related classes. FakeFS
doesn't support these methods out of the box, but you can define fake versions
yourself on the equivalent FakeFS classes. For example,
[FileMagic](https://rubygems.org/gems/ruby-filemagic) adds `File#content_type`.
A fake version can be provided as follows:

``` ruby
FakeFS::File.class_eval do
  def content_type
    'fake/file'
  end
end
```

[MockFS](http://mockfs.rubyforge.org/) comparison
----------------------------------

FakeFS provides a test suite and works with symlinks. It's also strictly a
test-time dependency: your actual library does not need to use or know about
FakeFS.


Caveats
-------

FakeFS internally uses the `Pathname` and `FileUtils` constants. If you use
these in your app, be certain you're properly requiring them and not counting
on FakeFS' own require.

As of v0.5.0, FakeFS's current working directory (i.e. `Dir.pwd`) is
independent of the real working directory. Previously if the real working
directory were, for example, `/Users/donovan/Desktop`, then FakeFS would use
that as the fake working directory too, even though it most likely didn't
exist. This caused all kinds of subtle bugs. Now the default working directory
is the only thing that is guaranteed to exist, namely the root (i.e. `/`). This
may be important when upgrading from v0.4.x to v0.5.x, especially if you depend
on the real working directory while using FakeFS.

FakeFS replaces File and FileUtils, but is not a filesystem replacement, so gems
that use strange commands or C might circumvent it.  For example, the `sqlite3`
gem will completely ignore any faked filesystem.

Speed?
------

<http://gist.github.com/156091>


Contributing
------------

Once you've made your great commits:

1. [Fork][0] FakeFS
2. Create a topic branch - `git checkout -b my_branch`
3. Push to your branch - `git push origin my_branch`
5. Open a [Pull Request][1]
5. That's it!

Meta
----

* Code: `git clone git://github.com/fakefs/fakefs.git`
* Home: <https://github.com/fakefs/fakefs>
* Bugs: <https://github.com/fakefs/fakefs/issues>
* Test: <https://travis-ci.org/fakefs/fakefs>
* Gems: <https://rubygems.org/gems/fakefs>

[0]: https://help.github.com/forking/
[1]: https://help.github.com/send-pull-requests/

Releasing
---------

1. `bundle exec rake bump:patch` or minor/major
2. `bundle exec rake release`