init

vendor/codeception/base/docs/modules/FTP.md

@@ -0,0 +1,429 @@
+# FTP
+
+
+
+Works with SFTP/FTP servers.
+
+In order to test the contents of a specific file stored on any remote FTP/SFTP system
+this module downloads a temporary file to the local system. The temporary directory is
+defined by default as ```tests/_data``` to specify a different directory set the tmp config
+option to your chosen path.
+
+Don't forget to create the folder and ensure its writable.
+
+Supported and tested FTP types are:
+
+* FTP
+* SFTP
+
+Connection uses php build in FTP client for FTP,
+connection to SFTP uses [phpseclib](http://phpseclib.sourceforge.net/) pulled in using composer.
+
+For SFTP, add [phpseclib](http://phpseclib.sourceforge.net/) to require list.
+```
+"require": {
+ "phpseclib/phpseclib": "0.3.6"
+}
+```
+
+## Status
+
+* Maintainer: **nathanmac**
+* Stability:
+    - FTP: **stable**
+    - SFTP: **stable**
+* Contact: nathan.macnamara@outlook.com
+
+## Config
+
+* type: ftp - type of connection ftp/sftp (defaults to ftp).
+* host *required* - hostname/ip address of the ftp server.
+* port: 21 - port number for the ftp server
+* timeout: 90 - timeout settings for connecting the ftp server.
+* user: anonymous - user to access ftp server, defaults to anonymous authentication.
+* password - password, defaults to empty for anonymous.
+* key - path to RSA key for sftp.
+* tmp - path to local directory for storing tmp files.
+* passive: true - Turns on or off passive mode (FTP only)
+* cleanup: true - remove tmp files from local directory on completion.
+
+### Example
+#### Example (FTP)
+
+    modules:
+       enabled: [FTP]
+       config:
+          FTP:
+             type: ftp
+             host: '127.0.0.1'
+             port: 21
+             timeout: 120
+             user: 'root'
+             password: 'root'
+             key: ~/.ssh/id_rsa
+             tmp: 'tests/_data/ftp'
+             passive: true
+             cleanup: false
+
+#### Example (SFTP)
+
+    modules:
+       enabled: [FTP]
+       config:
+          FTP:
+             type: sftp
+             host: '127.0.0.1'
+             port: 22
+             timeout: 120
+             user: 'root'
+             password: 'root'
+             key: ''
+             tmp: 'tests/_data/ftp'
+             cleanup: false
+
+
+This module extends the Filesystem module, file contents methods are inherited from this module.
+
+## Actions
+
+### amInPath
+ 
+Enters a directory on the ftp system - FTP root directory is used by default
+
+ * `param` $path
+
+
+### cleanDir
+ 
+Erases directory contents on the FTP/SFTP server
+
+``` php
+<?php
+$I->cleanDir('logs');
+?>
+```
+
+ * `param` $dirname
+
+
+### copyDir
+ 
+Currently not supported in this module, overwrite inherited method
+
+ * `param` $src
+ * `param` $dst
+
+
+### deleteDir
+ 
+Deletes directory with all subdirectories on the remote FTP/SFTP server
+
+``` php
+<?php
+$I->deleteDir('vendor');
+?>
+```
+
+ * `param` $dirname
+
+
+### deleteFile
+ 
+Deletes a file on the remote FTP/SFTP system
+
+``` php
+<?php
+$I->deleteFile('composer.lock');
+?>
+```
+
+ * `param` $filename
+
+
+### deleteThisFile
+ 
+Deletes a file
+
+
+### dontSeeFileFound
+ 
+Checks if file does not exist in path on the remote FTP/SFTP system
+
+ * `param` $filename
+ * `param string` $path
+
+
+### dontSeeFileFoundMatches
+ 
+Checks if file does not exist in path on the remote FTP/SFTP system, using regular expression as filename.
+DOES NOT OPEN the file when it's exists
+
+ * `param` $regex
+ * `param string` $path
+
+
+### dontSeeInThisFile
+ 
+Checks If opened file doesn't contain `text` in it
+
+``` php
+<?php
+$I->openFile('composer.json');
+$I->dontSeeInThisFile('codeception/codeception');
+?>
+```
+
+ * `param string` $text
+
+
+### grabDirectory
+ 
+Grabber method to return current working directory
+
+```php
+<?php
+$pwd = $I->grabDirectory();
+?>
+```
+
+ * `return` string
+
+
+### grabFileCount
+ 
+Grabber method for returning file/folders count in directory
+
+```php
+<?php
+$count = $I->grabFileCount();
+$count = $I->grabFileCount('TEST', false); // Include . .. .thumbs.db
+?>
+```
+
+ * `param string` $path
+ * `param bool` $ignore - suppress '.', '..' and '.thumbs.db'
+ * `return` int
+
+
+### grabFileList
+ 
+Grabber method for returning file/folders listing in an array
+
+```php
+<?php
+$files = $I->grabFileList();
+$count = $I->grabFileList('TEST', false); // Include . .. .thumbs.db
+?>
+```
+
+ * `param string` $path
+ * `param bool` $ignore - suppress '.', '..' and '.thumbs.db'
+ * `return` array
+
+
+### grabFileModified
+ 
+Grabber method to return last modified timestamp
+
+```php
+<?php
+$time = $I->grabFileModified('test.txt');
+?>
+```
+
+ * `param` $filename
+ * `return` bool
+
+
+### grabFileSize
+ 
+Grabber method to return file size
+
+```php
+<?php
+$size = $I->grabFileSize('test.txt');
+?>
+```
+
+ * `param` $filename
+ * `return` bool
+
+
+### loginAs
+ 
+Change the logged in user mid-way through your test, this closes the
+current connection to the server and initialises and new connection.
+
+On initiation of this modules you are automatically logged into
+the server using the specified config options or defaulted
+to anonymous user if not provided.
+
+``` php
+<?php
+$I->loginAs('user','password');
+?>
+```
+
+ * `param String` $user
+ * `param String` $password
+
+
+### makeDir
+ 
+Create a directory on the server
+
+``` php
+<?php
+$I->makeDir('vendor');
+?>
+```
+
+ * `param` $dirname
+
+
+### openFile
+ 
+Opens a file (downloads from the remote FTP/SFTP system to a tmp directory for processing)
+and stores it's content.
+
+Usage:
+
+``` php
+<?php
+$I->openFile('composer.json');
+$I->seeInThisFile('codeception/codeception');
+?>
+```
+
+ * `param` $filename
+
+
+### renameDir
+ 
+Rename/Move directory on the FTP/SFTP server
+
+``` php
+<?php
+$I->renameDir('vendor', 'vendor_old');
+?>
+```
+
+ * `param` $dirname
+ * `param` $rename
+
+
+### renameFile
+ 
+Rename/Move file on the FTP/SFTP server
+
+``` php
+<?php
+$I->renameFile('composer.lock', 'composer_old.lock');
+?>
+```
+
+ * `param` $filename
+ * `param` $rename
+
+
+### seeFileContentsEqual
+ 
+Checks the strict matching of file contents.
+Unlike `seeInThisFile` will fail if file has something more than expected lines.
+Better to use with HEREDOC strings.
+Matching is done after removing "\r" chars from file content.
+
+``` php
+<?php
+$I->openFile('process.pid');
+$I->seeFileContentsEqual('3192');
+?>
+```
+
+ * `param string` $text
+
+
+### seeFileFound
+ 
+Checks if file exists in path on the remote FTP/SFTP system.
+DOES NOT OPEN the file when it's exists
+
+``` php
+<?php
+$I->seeFileFound('UserModel.php','app/models');
+?>
+```
+
+ * `param` $filename
+ * `param string` $path
+
+
+### seeFileFoundMatches
+ 
+Checks if file exists in path on the remote FTP/SFTP system, using regular expression as filename.
+DOES NOT OPEN the file when it's exists
+
+ ``` php
+<?php
+$I->seeFileFoundMatches('/^UserModel_([0-9]{6}).php$/','app/models');
+?>
+```
+
+ * `param` $regex
+ * `param string` $path
+
+
+### seeInThisFile
+ 
+Checks If opened file has `text` in it.
+
+Usage:
+
+``` php
+<?php
+$I->openFile('composer.json');
+$I->seeInThisFile('codeception/codeception');
+?>
+```
+
+ * `param string` $text
+
+
+### seeNumberNewLines
+ 
+Checks If opened file has the `number` of new lines.
+
+Usage:
+
+``` php
+<?php
+$I->openFile('composer.json');
+$I->seeNumberNewLines(5);
+?>
+```
+
+ * `param int` $number New lines
+
+
+### seeThisFileMatches
+ 
+Checks that contents of currently opened file matches $regex
+
+ * `param string` $regex
+
+
+### writeToFile
+ 
+Saves contents to tmp file and uploads the FTP/SFTP system.
+Overwrites current file on server if exists.
+
+``` php
+<?php
+$I->writeToFile('composer.json', 'some data here');
+?>
+```
+
+ * `param` $filename
+ * `param` $contents
+
+<p>&nbsp;</p><div class="alert alert-warning">Module reference is taken from the source code. <a href="https://github.com/Codeception/Codeception/tree/2.4/src/Codeception/Module/FTP.php">Help us to improve documentation. Edit module reference</a></div>