forked from robotframework/robotframework
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathOperatingSystem.py
More file actions
1479 lines (1226 loc) · 62.8 KB
/
OperatingSystem.py
File metadata and controls
1479 lines (1226 loc) · 62.8 KB
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
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
# Copyright 2008-2015 Nokia Networks
# Copyright 2016- Robot Framework Foundation
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
import fnmatch
import glob
import io
import os
import shutil
import sys
import tempfile
import time
from robot.version import get_version
from robot.api import logger
from robot.utils import (abspath, ConnectionCache, console_decode, del_env_var,
get_env_var, get_env_vars, get_time, is_truthy,
is_unicode, normpath, parse_time, plural_or_not,
secs_to_timestamp, secs_to_timestr, seq2str,
set_env_var, timestr_to_secs, unic, CONSOLE_ENCODING,
IRONPYTHON, JYTHON, PY2, PY3, SYSTEM_ENCODING, WINDOWS)
__version__ = get_version()
PROCESSES = ConnectionCache('No active processes.')
class OperatingSystem(object):
"""A test library providing keywords for OS related tasks.
``OperatingSystem`` is Robot Framework's standard library that
enables various operating system related tasks to be performed in
the system where Robot Framework is running. It can, among other
things, execute commands (e.g. `Run`), create and remove files and
directories (e.g. `Create File`, `Remove Directory`), check
whether files or directories exists or contain something
(e.g. `File Should Exist`, `Directory Should Be Empty`) and
manipulate environment variables (e.g. `Set Environment Variable`).
== Table of contents ==
- `Path separators`
- `Pattern matching`
- `Tilde expansion`
- `Boolean arguments`
- `Example`
- `Shortcuts`
- `Keywords`
= Path separators =
Because Robot Framework uses the backslash (``\\``) as an escape character
in the test data, using a literal backslash requires duplicating it like
in ``c:\\\\path\\\\file.txt``. That can be inconvenient especially with
longer Windows paths, and thus all keywords expecting paths as arguments
convert forward slashes to backslashes automatically on Windows. This also
means that paths like ``${CURDIR}/path/file.txt`` are operating system
independent.
Notice that the automatic path separator conversion does not work if
the path is only a part of an argument like with `Run` and `Start Process`
keywords. In these cases the built-in variable ``${/}`` that contains
``\\`` or ``/``, depending on the operating system, can be used instead.
= Pattern matching =
Some keywords allow their arguments to be specified as
[http://en.wikipedia.org/wiki/Glob_(programming)|glob patterns] where:
| ``*`` | matches any string, even an empty string |
| ``?`` | matches any single character |
| ``[chars]`` | matches one character in the bracket |
| ``[!chars]`` | matches one character not in the bracket |
| ``[a-z]`` | matches one character from the range in the bracket |
| ``[!a-z]`` | matches one character not from the range in the bracket |
Unless otherwise noted, matching is case-insensitive on
case-insensitive operating systems such as Windows.
Starting from Robot Framework 2.9.1, globbing is not done if the given path
matches an existing file even if it would contain a glob pattern.
= Tilde expansion =
Paths beginning with ``~`` or ``~username`` are expanded to the current or
specified user's home directory, respectively. The resulting path is
operating system dependent, but typically e.g. ``~/robot`` is expanded to
``C:\\Users\\<user>\\robot`` on Windows and ``/home/<user>/robot`` on
Unixes.
The ``~username`` form does not work on Jython.
= Boolean arguments =
Some keywords accept arguments that are handled as Boolean values true or
false. If such an argument is given as a string, it is considered false if
it is an empty string or equal to ``FALSE``, ``NONE``, ``NO``, ``OFF`` or
``0``, case-insensitively. Other strings are considered true regardless
their value, and other argument types are tested using the same
[http://docs.python.org/library/stdtypes.html#truth|rules as in Python].
True examples:
| `Remove Directory` | ${path} | recursive=True | # Strings are generally true. |
| `Remove Directory` | ${path} | recursive=yes | # Same as the above. |
| `Remove Directory` | ${path} | recursive=${TRUE} | # Python ``True`` is true. |
| `Remove Directory` | ${path} | recursive=${42} | # Numbers other than 0 are true. |
False examples:
| `Remove Directory` | ${path} | recursive=False | # String ``false`` is false. |
| `Remove Directory` | ${path} | recursive=no | # Also string ``no`` is false. |
| `Remove Directory` | ${path} | recursive=${EMPTY} | # Empty string is false. |
| `Remove Directory` | ${path} | recursive=${FALSE} | # Python ``False`` is false. |
Considering string ``NONE`` false is new in Robot Framework 3.0.3 and
considering also ``OFF`` and ``0`` false is new in Robot Framework 3.1.
= Example =
| =Setting= | =Value= |
| Library | OperatingSystem |
| =Variable= | =Value= |
| ${PATH} | ${CURDIR}/example.txt |
| =Test Case= | =Action= | =Argument= | =Argument= |
| Example | Create File | ${PATH} | Some text |
| | File Should Exist | ${PATH} | |
| | Copy File | ${PATH} | ~/file.txt |
| | ${output} = | Run | ${TEMPDIR}${/}script.py arg |
"""
ROBOT_LIBRARY_SCOPE = 'GLOBAL'
ROBOT_LIBRARY_VERSION = __version__
def run(self, command):
"""Runs the given command in the system and returns the output.
The execution status of the command *is not checked* by this
keyword, and it must be done separately based on the returned
output. If the execution return code is needed, either `Run
And Return RC` or `Run And Return RC And Output` can be used.
The standard error stream is automatically redirected to the standard
output stream by adding ``2>&1`` after the executed command. This
automatic redirection is done only when the executed command does not
contain additional output redirections. You can thus freely forward
the standard error somewhere else, for example, like
``my_command 2>stderr.txt``.
The returned output contains everything written into the standard
output or error streams by the command (unless either of them
is redirected explicitly). Many commands add an extra newline
(``\\n``) after the output to make it easier to read in the
console. To ease processing the returned output, this possible
trailing newline is stripped by this keyword.
Examples:
| ${output} = | Run | ls -lhF /tmp |
| Log | ${output} |
| ${result} = | Run | ${CURDIR}${/}tester.py arg1 arg2 |
| Should Not Contain | ${result} | FAIL |
| ${stdout} = | Run | /opt/script.sh 2>/tmp/stderr.txt |
| Should Be Equal | ${stdout} | TEST PASSED |
| File Should Be Empty | /tmp/stderr.txt |
*TIP:* `Run Process` keyword provided by the
[http://robotframework.org/robotframework/latest/libraries/Process.html|
Process library] supports better process configuration and is generally
recommended as a replacement for this keyword.
"""
return self._run(command)[1]
def run_and_return_rc(self, command):
"""Runs the given command in the system and returns the return code.
The return code (RC) is returned as a positive integer in
range from 0 to 255 as returned by the executed command. On
some operating systems (notable Windows) original return codes
can be something else, but this keyword always maps them to
the 0-255 range. Since the RC is an integer, it must be
checked e.g. with the keyword `Should Be Equal As Integers`
instead of `Should Be Equal` (both are built-in keywords).
Examples:
| ${rc} = | Run and Return RC | ${CURDIR}${/}script.py arg |
| Should Be Equal As Integers | ${rc} | 0 |
| ${rc} = | Run and Return RC | /path/to/example.rb arg1 arg2 |
| Should Be True | 0 < ${rc} < 42 |
See `Run` and `Run And Return RC And Output` if you need to get the
output of the executed command.
*TIP:* `Run Process` keyword provided by the
[http://robotframework.org/robotframework/latest/libraries/Process.html|
Process library] supports better process configuration and is generally
recommended as a replacement for this keyword.
"""
return self._run(command)[0]
def run_and_return_rc_and_output(self, command):
"""Runs the given command in the system and returns the RC and output.
The return code (RC) is returned similarly as with `Run And Return RC`
and the output similarly as with `Run`.
Examples:
| ${rc} | ${output} = | Run and Return RC and Output | ${CURDIR}${/}mytool |
| Should Be Equal As Integers | ${rc} | 0 |
| Should Not Contain | ${output} | FAIL |
| ${rc} | ${stdout} = | Run and Return RC and Output | /opt/script.sh 2>/tmp/stderr.txt |
| Should Be True | ${rc} > 42 |
| Should Be Equal | ${stdout} | TEST PASSED |
| File Should Be Empty | /tmp/stderr.txt |
*TIP:* `Run Process` keyword provided by the
[http://robotframework.org/robotframework/latest/libraries/Process.html|
Process library] supports better process configuration and is generally
recommended as a replacement for this keyword.
"""
return self._run(command)
def _run(self, command):
process = _Process(command)
self._info("Running command '%s'." % process)
stdout = process.read()
rc = process.close()
return rc, stdout
def get_file(self, path, encoding='UTF-8', encoding_errors='strict'):
"""Returns the contents of a specified file.
This keyword reads the specified file and returns the contents.
Line breaks in content are converted to platform independent form.
See also `Get Binary File`.
``encoding`` defines the encoding of the file. The default value is
``UTF-8``, which means that UTF-8 and ASCII encoded files are read
correctly. In addition to the encodings supported by the underlying
Python implementation, the following special encoding values can be
used:
- ``SYSTEM``: Use the default system encoding.
- ``CONSOLE``: Use the console encoding. Outside Windows this is same
as the system encoding.
``encoding_errors`` argument controls what to do if decoding some bytes
fails. All values accepted by ``decode`` method in Python are valid, but
in practice the following values are most useful:
- ``strict``: Fail if characters cannot be decoded (default).
- ``ignore``: Ignore characters that cannot be decoded.
- ``replace``: Replace characters that cannot be decoded with
a replacement character.
Support for ``SYSTEM`` and ``CONSOLE`` encodings in Robot Framework 3.0.
"""
path = self._absnorm(path)
self._link("Getting file '%s'.", path)
encoding = self._map_encoding(encoding)
if IRONPYTHON:
# https://github.com/IronLanguages/main/issues/1233
with open(path) as f:
content = f.read().decode(encoding, encoding_errors)
else:
with io.open(path, encoding=encoding, errors=encoding_errors,
newline='') as f:
content = f.read()
return content.replace('\r\n', '\n')
def _map_encoding(self, encoding):
# Python 3 opens files in native system encoding by default.
if PY3 and encoding.upper() == 'SYSTEM':
return None
return {'SYSTEM': SYSTEM_ENCODING,
'CONSOLE': CONSOLE_ENCODING}.get(encoding.upper(), encoding)
def get_binary_file(self, path):
"""Returns the contents of a specified file.
This keyword reads the specified file and returns the contents as is.
See also `Get File`.
"""
path = self._absnorm(path)
self._link("Getting file '%s'.", path)
with open(path, 'rb') as f:
return bytes(f.read())
def grep_file(self, path, pattern, encoding='UTF-8', encoding_errors='strict'):
"""Returns the lines of the specified file that match the ``pattern``.
This keyword reads a file from the file system using the defined
``path``, ``encoding`` and ``encoding_errors`` similarly as `Get File`.
A difference is that only the lines that match the given ``pattern`` are
returned. Lines are returned as a single string catenated back together
with newlines and the number of matched lines is automatically logged.
Possible trailing newline is never returned.
A line matches if it contains the ``pattern`` anywhere in it and
it *does not need to match the pattern fully*. The pattern
matching syntax is explained in `introduction`, and in this
case matching is case-sensitive.
Examples:
| ${errors} = | Grep File | /var/log/myapp.log | ERROR |
| ${ret} = | Grep File | ${CURDIR}/file.txt | [Ww]ildc??d ex*ple |
If more complex pattern matching is needed, it is possible to use
`Get File` in combination with String library keywords like `Get
Lines Matching Regexp`.
"""
pattern = '*%s*' % pattern
path = self._absnorm(path)
lines = []
total_lines = 0
self._link("Reading file '%s'.", path)
with io.open(path, encoding=encoding, errors=encoding_errors) as f:
for line in f.readlines():
total_lines += 1
line = line.rstrip('\r\n')
if fnmatch.fnmatchcase(line, pattern):
lines.append(line)
self._info('%d out of %d lines matched' % (len(lines), total_lines))
return '\n'.join(lines)
def log_file(self, path, encoding='UTF-8', encoding_errors='strict'):
"""Wrapper for `Get File` that also logs the returned file.
The file is logged with the INFO level. If you want something else,
just use `Get File` and the built-in keyword `Log` with the desired
level.
See `Get File` for more information about ``encoding`` and
``encoding_errors`` arguments.
"""
content = self.get_file(path, encoding, encoding_errors)
self._info(content)
return content
# File and directory existence
def should_exist(self, path, msg=None):
"""Fails unless the given path (file or directory) exists.
The path can be given as an exact path or as a glob pattern.
The pattern matching syntax is explained in `introduction`.
The default error message can be overridden with the ``msg`` argument.
"""
path = self._absnorm(path)
if not self._glob(path):
self._fail(msg, "Path '%s' does not exist." % path)
self._link("Path '%s' exists.", path)
def should_not_exist(self, path, msg=None):
"""Fails if the given path (file or directory) exists.
The path can be given as an exact path or as a glob pattern.
The pattern matching syntax is explained in `introduction`.
The default error message can be overridden with the ``msg`` argument.
"""
path = self._absnorm(path)
matches = self._glob(path)
if matches:
self._fail(msg, self._get_matches_error('Path', path, matches))
self._link("Path '%s' does not exist.", path)
def _glob(self, path):
return glob.glob(path) if not os.path.exists(path) else [path]
def _get_matches_error(self, what, path, matches):
if not self._is_glob_path(path):
return "%s '%s' exists." % (what, path)
return "%s '%s' matches %s." % (what, path, seq2str(sorted(matches)))
def _is_glob_path(self, path):
return '*' in path or '?' in path or ('[' in path and ']' in path)
def file_should_exist(self, path, msg=None):
"""Fails unless the given ``path`` points to an existing file.
The path can be given as an exact path or as a glob pattern.
The pattern matching syntax is explained in `introduction`.
The default error message can be overridden with the ``msg`` argument.
"""
path = self._absnorm(path)
matches = [p for p in self._glob(path) if os.path.isfile(p)]
if not matches:
self._fail(msg, "File '%s' does not exist." % path)
self._link("File '%s' exists.", path)
def file_should_not_exist(self, path, msg=None):
"""Fails if the given path points to an existing file.
The path can be given as an exact path or as a glob pattern.
The pattern matching syntax is explained in `introduction`.
The default error message can be overridden with the ``msg`` argument.
"""
path = self._absnorm(path)
matches = [p for p in self._glob(path) if os.path.isfile(p)]
if matches:
self._fail(msg, self._get_matches_error('File', path, matches))
self._link("File '%s' does not exist.", path)
def directory_should_exist(self, path, msg=None):
"""Fails unless the given path points to an existing directory.
The path can be given as an exact path or as a glob pattern.
The pattern matching syntax is explained in `introduction`.
The default error message can be overridden with the ``msg`` argument.
"""
path = self._absnorm(path)
matches = [p for p in self._glob(path) if os.path.isdir(p)]
if not matches:
self._fail(msg, "Directory '%s' does not exist." % path)
self._link("Directory '%s' exists.", path)
def directory_should_not_exist(self, path, msg=None):
"""Fails if the given path points to an existing file.
The path can be given as an exact path or as a glob pattern.
The pattern matching syntax is explained in `introduction`.
The default error message can be overridden with the ``msg`` argument.
"""
path = self._absnorm(path)
matches = [p for p in self._glob(path) if os.path.isdir(p)]
if matches:
self._fail(msg, self._get_matches_error('Directory', path, matches))
self._link("Directory '%s' does not exist.", path)
# Waiting file/dir to appear/disappear
def wait_until_removed(self, path, timeout='1 minute'):
"""Waits until the given file or directory is removed.
The path can be given as an exact path or as a glob pattern.
The pattern matching syntax is explained in `introduction`.
If the path is a pattern, the keyword waits until all matching
items are removed.
The optional ``timeout`` can be used to control the maximum time of
waiting. The timeout is given as a timeout string, e.g. in a format
``15 seconds``, ``1min 10s`` or just ``10``. The time string format is
described in an appendix of Robot Framework User Guide.
If the timeout is negative, the keyword is never timed-out. The keyword
returns immediately, if the path does not exist in the first place.
"""
path = self._absnorm(path)
timeout = timestr_to_secs(timeout)
maxtime = time.time() + timeout
while self._glob(path):
if timeout >= 0 and time.time() > maxtime:
self._fail("'%s' was not removed in %s."
% (path, secs_to_timestr(timeout)))
time.sleep(0.1)
self._link("'%s' was removed.", path)
def wait_until_created(self, path, timeout='1 minute'):
"""Waits until the given file or directory is created.
The path can be given as an exact path or as a glob pattern.
The pattern matching syntax is explained in `introduction`.
If the path is a pattern, the keyword returns when an item matching
it is created.
The optional ``timeout`` can be used to control the maximum time of
waiting. The timeout is given as a timeout string, e.g. in a format
``15 seconds``, ``1min 10s`` or just ``10``. The time string format is
described in an appendix of Robot Framework User Guide.
If the timeout is negative, the keyword is never timed-out. The keyword
returns immediately, if the path already exists.
"""
path = self._absnorm(path)
timeout = timestr_to_secs(timeout)
maxtime = time.time() + timeout
while not self._glob(path):
if timeout >= 0 and time.time() > maxtime:
self._fail("'%s' was not created in %s."
% (path, secs_to_timestr(timeout)))
time.sleep(0.1)
self._link("'%s' was created.", path)
# Dir/file empty
def directory_should_be_empty(self, path, msg=None):
"""Fails unless the specified directory is empty.
The default error message can be overridden with the ``msg`` argument.
"""
path = self._absnorm(path)
items = self._list_dir(path)
if items:
self._fail(msg, "Directory '%s' is not empty. Contents: %s."
% (path, seq2str(items, lastsep=', ')))
self._link("Directory '%s' is empty.", path)
def directory_should_not_be_empty(self, path, msg=None):
"""Fails if the specified directory is empty.
The default error message can be overridden with the ``msg`` argument.
"""
path = self._absnorm(path)
items = self._list_dir(path)
if not items:
self._fail(msg, "Directory '%s' is empty." % path)
self._link("Directory '%%s' contains %d item%s."
% (len(items), plural_or_not(items)), path)
def file_should_be_empty(self, path, msg=None):
"""Fails unless the specified file is empty.
The default error message can be overridden with the ``msg`` argument.
"""
path = self._absnorm(path)
if not os.path.isfile(path):
self._error("File '%s' does not exist." % path)
size = os.stat(path).st_size
if size > 0:
self._fail(msg,
"File '%s' is not empty. Size: %d bytes." % (path, size))
self._link("File '%s' is empty.", path)
def file_should_not_be_empty(self, path, msg=None):
"""Fails if the specified directory is empty.
The default error message can be overridden with the ``msg`` argument.
"""
path = self._absnorm(path)
if not os.path.isfile(path):
self._error("File '%s' does not exist." % path)
size = os.stat(path).st_size
if size == 0:
self._fail(msg, "File '%s' is empty." % path)
self._link("File '%%s' contains %d bytes." % size, path)
# Creating and removing files and directory
def create_file(self, path, content='', encoding='UTF-8'):
"""Creates a file with the given content and encoding.
If the directory where the file is created does not exist, it is
automatically created along with possible missing intermediate
directories. Possible existing file is overwritten.
On Windows newline characters (``\\n``) in content are automatically
converted to Windows native newline sequence (``\\r\\n``).
See `Get File` for more information about possible ``encoding`` values,
including special values ``SYSTEM`` and ``CONSOLE``.
Examples:
| Create File | ${dir}/example.txt | Hello, world! | |
| Create File | ${path} | Hyv\\xe4 esimerkki | Latin-1 |
| Create File | /tmp/foo.txt | 3\\nlines\\nhere\\n | SYSTEM |
Use `Append To File` if you want to append to an existing file
and `Create Binary File` if you need to write bytes without encoding.
`File Should Not Exist` can be used to avoid overwriting existing
files.
The support for ``SYSTEM`` and ``CONSOLE`` encodings is new in Robot
Framework 3.0. Automatically converting ``\\n`` to ``\\r\\n`` on
Windows is new in Robot Framework 3.1.
"""
path = self._write_to_file(path, content, encoding)
self._link("Created file '%s'.", path)
def _write_to_file(self, path, content, encoding=None, mode='w'):
path = self._absnorm(path)
parent = os.path.dirname(path)
if not os.path.exists(parent):
os.makedirs(parent)
# io.open() only accepts Unicode, not byte-strings, in text mode.
# We expect possible byte-strings to be all ASCII.
if PY2 and isinstance(content, str) and 'b' not in mode:
content = unicode(content)
if encoding:
encoding = self._map_encoding(encoding)
with io.open(path, mode, encoding=encoding) as f:
f.write(content)
return path
def create_binary_file(self, path, content):
"""Creates a binary file with the given content.
If content is given as a Unicode string, it is first converted to bytes
character by character. All characters with ordinal below 256 can be
used and are converted to bytes with same values. Using characters
with higher ordinal is an error.
Byte strings, and possible other types, are written to the file as is.
If the directory for the file does not exist, it is created, along
with missing intermediate directories.
Examples:
| Create Binary File | ${dir}/example.png | ${image content} |
| Create Binary File | ${path} | \\x01\\x00\\xe4\\x00 |
Use `Create File` if you want to create a text file using a certain
encoding. `File Should Not Exist` can be used to avoid overwriting
existing files.
"""
if is_unicode(content):
content = bytes(bytearray(ord(c) for c in content))
path = self._write_to_file(path, content, mode='wb')
self._link("Created binary file '%s'.", path)
def append_to_file(self, path, content, encoding='UTF-8'):
"""Appends the given content to the specified file.
If the file exists, the given text is written to its end. If the file
does not exist, it is created.
Other than not overwriting possible existing files, this keyword works
exactly like `Create File`. See its documentation for more details
about the usage.
Note that special encodings ``SYSTEM`` and ``CONSOLE`` only work
with this keyword starting from Robot Framework 3.1.2.
"""
path = self._write_to_file(path, content, encoding, mode='a')
self._link("Appended to file '%s'.", path)
def remove_file(self, path):
"""Removes a file with the given path.
Passes if the file does not exist, but fails if the path does
not point to a regular file (e.g. it points to a directory).
The path can be given as an exact path or as a glob pattern.
The pattern matching syntax is explained in `introduction`.
If the path is a pattern, all files matching it are removed.
"""
path = self._absnorm(path)
matches = self._glob(path)
if not matches:
self._link("File '%s' does not exist.", path)
for match in matches:
if not os.path.isfile(match):
self._error("Path '%s' is not a file." % match)
os.remove(match)
self._link("Removed file '%s'.", match)
def remove_files(self, *paths):
"""Uses `Remove File` to remove multiple files one-by-one.
Example:
| Remove Files | ${TEMPDIR}${/}foo.txt | ${TEMPDIR}${/}bar.txt | ${TEMPDIR}${/}zap.txt |
"""
for path in paths:
self.remove_file(path)
def empty_directory(self, path):
"""Deletes all the content from the given directory.
Deletes both files and sub-directories, but the specified directory
itself if not removed. Use `Remove Directory` if you want to remove
the whole directory.
"""
path = self._absnorm(path)
for item in self._list_dir(path, absolute=True):
if os.path.isdir(item):
shutil.rmtree(item)
else:
os.remove(item)
self._link("Emptied directory '%s'.", path)
def create_directory(self, path):
"""Creates the specified directory.
Also possible intermediate directories are created. Passes if the
directory already exists, but fails if the path exists and is not
a directory.
"""
path = self._absnorm(path)
if os.path.isdir(path):
self._link("Directory '%s' already exists.", path )
elif os.path.exists(path):
self._error("Path '%s' is not a directory." % path)
else:
os.makedirs(path)
self._link("Created directory '%s'.", path)
def remove_directory(self, path, recursive=False):
"""Removes the directory pointed to by the given ``path``.
If the second argument ``recursive`` is given a true value (see
`Boolean arguments`), the directory is removed recursively. Otherwise
removing fails if the directory is not empty.
If the directory pointed to by the ``path`` does not exist, the keyword
passes, but it fails, if the ``path`` points to a file.
"""
path = self._absnorm(path)
if not os.path.exists(path):
self._link("Directory '%s' does not exist.", path)
elif not os.path.isdir(path):
self._error("Path '%s' is not a directory." % path)
else:
if is_truthy(recursive):
shutil.rmtree(path)
else:
self.directory_should_be_empty(
path, "Directory '%s' is not empty." % path)
os.rmdir(path)
self._link("Removed directory '%s'.", path)
# Moving and copying files and directories
def copy_file(self, source, destination):
"""Copies the source file into the destination.
Source must be a path to an existing file or a glob pattern (see
`Pattern matching`) that matches exactly one file. How the
destination is interpreted is explained below.
1) If the destination is an existing file, the source file is copied
over it.
2) If the destination is an existing directory, the source file is
copied into it. A possible file with the same name as the source is
overwritten.
3) If the destination does not exist and it ends with a path
separator (``/`` or ``\\``), it is considered a directory. That
directory is created and a source file copied into it.
Possible missing intermediate directories are also created.
4) If the destination does not exist and it does not end with a path
separator, it is considered a file. If the path to the file does not
exist, it is created.
The resulting destination path is returned since Robot Framework 2.9.2.
See also `Copy Files`, `Move File`, and `Move Files`.
"""
source, destination = \
self._prepare_copy_and_move_file(source, destination)
if not self._are_source_and_destination_same_file(source, destination):
source, destination = self._atomic_copy(source, destination)
self._link("Copied file from '%s' to '%s'.", source, destination)
return destination
def _prepare_copy_and_move_file(self, source, destination):
source = self._normalize_copy_and_move_source(source)
destination = self._normalize_copy_and_move_destination(destination)
if os.path.isdir(destination):
destination = os.path.join(destination, os.path.basename(source))
return source, destination
def _normalize_copy_and_move_source(self, source):
source = self._absnorm(source)
sources = self._glob(source)
if len(sources) > 1:
self._error("Multiple matches with source pattern '%s'." % source)
if sources:
source = sources[0]
if not os.path.exists(source):
self._error("Source file '%s' does not exist." % source)
if not os.path.isfile(source):
self._error("Source file '%s' is not a regular file." % source)
return source
def _normalize_copy_and_move_destination(self, destination):
is_dir = os.path.isdir(destination) or destination.endswith(('/', '\\'))
destination = self._absnorm(destination)
directory = destination if is_dir else os.path.dirname(destination)
self._ensure_destination_directory_exists(directory)
return destination
def _ensure_destination_directory_exists(self, path):
if not os.path.exists(path):
os.makedirs(path)
elif not os.path.isdir(path):
self._error("Destination '%s' exists and is not a directory." % path)
def _are_source_and_destination_same_file(self, source, destination):
if self._force_normalize(source) == self._force_normalize(destination):
self._link("Source '%s' and destination '%s' point to the same "
"file.", source, destination)
return True
return False
def _force_normalize(self, path):
# TODO: Should normalize_path also support link normalization?
# TODO: Should we handle dos paths like 'exampl~1.txt'?
return os.path.realpath(normpath(path, case_normalize=True))
def _atomic_copy(self, source, destination):
"""Copy file atomically (or at least try to).
This method tries to ensure that a file copy operation will not fail
if the destination file is removed during copy operation. The problem
is that copying a file is typically not an atomic operation.
Luckily moving files is atomic in almost every platform, assuming files
are on the same filesystem, and we can use that as a workaround:
- First move the source to a temporary directory that is ensured to
be on the same filesystem as the destination.
- Move the temporary file over the real destination.
See also https://github.com/robotframework/robotframework/issues/1502
"""
temp_directory = tempfile.mkdtemp(dir=os.path.dirname(destination))
temp_file = os.path.join(temp_directory, os.path.basename(source))
try:
shutil.copy(source, temp_file)
if os.path.exists(destination):
os.remove(destination)
shutil.move(temp_file, destination)
finally:
shutil.rmtree(temp_directory)
return source, destination
def move_file(self, source, destination):
"""Moves the source file into the destination.
Arguments have exactly same semantics as with `Copy File` keyword.
Destination file path is returned since Robot Framework 2.9.2.
If the source and destination are on the same filesystem, rename
operation is used. Otherwise file is copied to the destination
filesystem and then removed from the original filesystem.
See also `Move Files`, `Copy File`, and `Copy Files`.
"""
source, destination = \
self._prepare_copy_and_move_file(source, destination)
if not self._are_source_and_destination_same_file(destination, source):
shutil.move(source, destination)
self._link("Moved file from '%s' to '%s'.", source, destination)
return destination
def copy_files(self, *sources_and_destination):
"""Copies specified files to the target directory.
Source files can be given as exact paths and as glob patterns (see
`Pattern matching`). At least one source must be given, but it is
not an error if it is a pattern that does not match anything.
Last argument must be the destination directory. If the destination
does not exist, it will be created.
Examples:
| Copy Files | ${dir}/file1.txt | ${dir}/file2.txt | ${dir2} |
| Copy Files | ${dir}/file-*.txt | ${dir2} | |
See also `Copy File`, `Move File`, and `Move Files`.
"""
sources, destination \
= self._prepare_copy_and_move_files(sources_and_destination)
for source in sources:
self.copy_file(source, destination)
def _prepare_copy_and_move_files(self, items):
if len(items) < 2:
self._error('Must contain destination and at least one source.')
sources = self._glob_files(items[:-1])
destination = self._absnorm(items[-1])
self._ensure_destination_directory_exists(destination)
return sources, destination
def _glob_files(self, patterns):
files = []
for pattern in patterns:
files.extend(self._glob(self._absnorm(pattern)))
return files
def move_files(self, *sources_and_destination):
"""Moves specified files to the target directory.
Arguments have exactly same semantics as with `Copy Files` keyword.
See also `Move File`, `Copy File`, and `Copy Files`.
"""
sources, destination \
= self._prepare_copy_and_move_files(sources_and_destination)
for source in sources:
self.move_file(source, destination)
def copy_directory(self, source, destination):
"""Copies the source directory into the destination.
If the destination exists, the source is copied under it. Otherwise
the destination directory and the possible missing intermediate
directories are created.
"""
source, destination \
= self._prepare_copy_and_move_directory(source, destination)
try:
shutil.copytree(source, destination)
except shutil.Error:
# https://github.com/robotframework/robotframework/issues/2321
if not (WINDOWS and JYTHON):
raise
self._link("Copied directory from '%s' to '%s'.", source, destination)
def _prepare_copy_and_move_directory(self, source, destination):
source = self._absnorm(source)
destination = self._absnorm(destination)
if not os.path.exists(source):
self._error("Source '%s' does not exist." % source)
if not os.path.isdir(source):
self._error("Source '%s' is not a directory." % source)
if os.path.exists(destination) and not os.path.isdir(destination):
self._error("Destination '%s' is not a directory." % destination)
if os.path.exists(destination):
base = os.path.basename(source)
destination = os.path.join(destination, base)
else:
parent = os.path.dirname(destination)
if not os.path.exists(parent):
os.makedirs(parent)
return source, destination
def move_directory(self, source, destination):
"""Moves the source directory into a destination.
Uses `Copy Directory` keyword internally, and ``source`` and
``destination`` arguments have exactly same semantics as with
that keyword.
"""
source, destination \
= self._prepare_copy_and_move_directory(source, destination)
shutil.move(source, destination)
self._link("Moved directory from '%s' to '%s'.", source, destination)
# Environment Variables
def get_environment_variable(self, name, default=None):
"""Returns the value of an environment variable with the given name.
If no such environment variable is set, returns the default value, if
given. Otherwise fails the test case.
Returned variables are automatically decoded to Unicode using
the system encoding.
Note that you can also access environment variables directly using
the variable syntax ``%{ENV_VAR_NAME}``.
"""
value = get_env_var(name, default)
if value is None:
self._error("Environment variable '%s' does not exist." % name)
return value
def set_environment_variable(self, name, value):
"""Sets an environment variable to a specified value.
Values are converted to strings automatically. Set variables are
automatically encoded using the system encoding.
"""
set_env_var(name, value)
self._info("Environment variable '%s' set to value '%s'."
% (name, value))
def append_to_environment_variable(self, name, *values, **config):
"""Appends given ``values`` to environment variable ``name``.
If the environment variable already exists, values are added after it,
and otherwise a new environment variable is created.
Values are, by default, joined together using the operating system
path separator (``;`` on Windows, ``:`` elsewhere). This can be changed
by giving a separator after the values like ``separator=value``. No
other configuration parameters are accepted.
Examples (assuming ``NAME`` and ``NAME2`` do not exist initially):
| Append To Environment Variable | NAME | first | |
| Should Be Equal | %{NAME} | first | |
| Append To Environment Variable | NAME | second | third |
| Should Be Equal | %{NAME} | first${:}second${:}third |
| Append To Environment Variable | NAME2 | first | separator=- |
| Should Be Equal | %{NAME2} | first | |
| Append To Environment Variable | NAME2 | second | separator=- |
| Should Be Equal | %{NAME2} | first-second |
"""
sentinel = object()
initial = self.get_environment_variable(name, sentinel)
if initial is not sentinel:
values = (initial,) + values
separator = config.pop('separator', os.pathsep)
if config:
config = ['='.join(i) for i in sorted(config.items())]
self._error('Configuration %s not accepted.'
% seq2str(config, lastsep=' or '))
self.set_environment_variable(name, separator.join(values))
def remove_environment_variable(self, *names):
"""Deletes the specified environment variable.